gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-06-11 04:31:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Expand new Usage/Markdown Docu (#203)

Browse Source 
As promised in [Gitea Pull #34105](https://github.com/go-gitea/gitea/pull/34105), I wanted to contribute documentation for MarkDown.

You were so fast in adding the page that I had to start over my local-only draft 😄 🚀

I'm not sure how you prefer your commits (I'm new to Gitea), so I've split them for simplest review and dropping of unwanted changes.

Co-authored-by: Jules Kerssemakers <j.kerssemakers@gsi.de>
Reviewed-on: https://gitea.com/gitea/docs/pulls/203
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: juke <juke@noreply.gitea.com>
Co-committed-by: juke <juke@noreply.gitea.com>
This commit is contained in:
juke
2025-04-10 20:15:37 +00:00
committed by Lunny Xiao
parent ac2186b6fb
commit 1a85ffdab8
1 changed files with 33 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/usage/markdown.md
View File

@@ -3,16 +3,28 @@ date: "2025-04-05T00:00:00+08:00"
slug: "markdown"
---
# Markdown rendering
# Markdown
Gitea supports most of GitHub markdown features:
Gitea uses MarkDown structured text in many places, you can recognise it by the `.md` file extension.
Markdown is plain text format for writing structured documents, allowing one to write
"plain" text files that nonetheless have _"fancy"_ **formatting**, while still keeping the plain-text version readable.
Unfortunately, due to historical implementation differences, many subtle dialects exist.
To avoid adding to the confusion, Gitea tries to follow "[GitHub Flavoured Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/)" as close as possible.
"GFM" is an extension on top of the rigorously-specified [CommonMark](https://commonmark.org/) standard.
CommonMark flavours are used by most major web platforms (e.g. Reddit, Stack Overflow, Discourse)
and git forges (GitHub, GitLab and our very own Gitea), thus you shouldn't run into any surprises with Gitea.
For a quick introduction to the syntax and features of GitHub Flavoured Markdown, see the GitHub documentation:
- [Basic formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
- [Advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting)
For a deeper history about CommonMark, its spec, and its reason for existence, see [CommonMark.org](https://commonmark.org/).
## Rendering options
Some Gitea's markdown rendering behaviors could be fine-tuned by global config options, see the `[markdown]` config section in the `app.example.ini`
Some Gitea's markdown rendering behaviors can be fine-tuned by global config options, see the `[markdown]` config section in the `app.example.ini`
## Link path resolving
@@ -23,15 +35,27 @@ When rendering links for `<a href>`, `<img src>` and `<video src>`, Gitea resolv
- In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link: `/owner-name/repo-name`.
- In a repository file context (markdown files in the repository), the base path is current git ref path.
To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax.
### Special link tokens
To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax.
This will always resolve to Gitea's ROOT_URL.
Gitea also supports GitHub's `?raw=1` query parameter.
A request to `/owner-name/repo-name/src/branch/main/file?raw=1` will be redirected to
`/owner-name/repo-name/raw/branch/main/file`. This makes it possible to target raw contents from relative links
(normally, the `src/` section of the path is provided automatically by Gitea and cannot be overriden).
### Link handling examples
For example, when rendering a markdown file in `/owner-name/repo-name/src/branch/main/dir`:
- Link `sub/file`is resolved to `/owner-name/repo-name/src/branch/main/dir/sub/file`
- Link `/sub/file`is resolved to `/owner-name/repo-name/src/branch/main/sub/file`
- If the link is used as `src` of an image or video, then it is resolved to `/owner-name/repo-name/raw/...`
- Link `/:root/any-path` is always resolved to `/any-path` without any further processing.
1) Absolute with scheme: Link `https://example.org` will be rendered as-is.
2) Relative from current file: Link `sub/file`is resolved to `/owner-name/repo-name/src/branch/main/dir/sub/file`
3) Relative from repo root: Link `/sub/file` (note leading slash) is resolved to `/owner-name/repo-name/src/branch/main/sub/file`
4) Raw media: If the link is used as `src` of an image or video, then it is resolved to `/owner-name/repo-name/raw/...`
5) Raw relative: `sub/file?raw=1` will resolve to `/owner-name/repo-name/src/branch/main/dir/sub/file?raw=1`,
which will redirect to `/owner-name/repo-name/raw/branch/main/dir/sub/file`.
6) explicit root: Link `/:root/any-path` is always resolved to `$ROOT_URL/any-path` without any further processing.
Gitea also supports GitHub's `?raw=1` query parameter, a request to `/owner-name/repo-name/src/branch/main/file?raw=1` will be redirected to `/owner-name/repo-name/raw/branch/main/file` to make browsers able to load the raw content of the file.
## Issue and pull-request reference