完成文档部分内容

2025-07-29 20:56:05 +08:00
parent 1e3e4d18ae
commit 81217e1e64
68 changed files with 6384 additions and 71 deletions
--- a/docs/document/usage/markdown.md
+++ b/docs/document/usage/markdown.md
@@ -0,0 +1,102 @@
+---
+date: "2025-04-05T00:00:00+08:00"
+slug: "markdown"
+---
+
+# 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)](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 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.
+
+### 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`:
+  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.
+
+
+## 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
+```
+````