Markdown
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)" as close as possible. "GFM" is an extension on top of the rigorously-specified CommonMark 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:
For a deeper history about CommonMark, its spec, and its reason for existence, see CommonMark.org.
Rendering options
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
When rendering links for <a href>
, <img src>
and <video src>
, Gitea resolves the link paths in the rendering context.
- If the link is an absolute path with scheme, the link is kept as-is.
- If the link is an URL path, it is resolved with the base path of current rendering context.
- 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.
- In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link:
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
:
- Absolute with scheme: Link
https://example.org
will be rendered as-is. - Relative from current file: Link
sub/file
is resolved to/owner-name/repo-name/src/branch/main/dir/sub/file
- Relative from repo root: Link
/sub/file
(note leading slash) is resolved to/owner-name/repo-name/src/branch/main/sub/file
- Raw media: If the link is used as
src
of an image or video, then it is resolved to/owner-name/repo-name/raw/...
- 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
. - explicit root: Link
/:root/any-path
is always resolved to$ROOT_URL/any-path
without any further processing.
Issue and pull-request reference
Using issue/pull-request numbers in a list:
* #123
* #456
It will be rendered with issue titles to:
* the issue title (#123)
* the other issue title (#456)
Math expressions
Gitea supports GitHub-like math expression formatting.
Inline expression
$\alpha$
: quoted by single-dollar$
$$\alpha$$
: quoted by double-dollar$$
$`\alpha`$
: quoted by dollar with backquotes, the backquotes could repeat like normal code blocks.
Block expression
Using $$
:
$$
\alpha
$$
Using code-block with language:
```math
\alpha
```