Add markdown usage (#198)

First simple version

Reviewed-on: https://gitea.com/gitea/docs/pulls/198
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
Co-committed-by: wxiaoguang <wxiaoguang@gmail.com>

docs/administration/config-cheat-sheet.md

@@ -277,17 +277,23 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 
 ## Markdown (`markdown`)
 
-- `ENABLE_HARD_LINE_BREAK_IN_COMMENTS`: **true**: Render soft line breaks as hard line breaks in comments, which
+- `RENDER_OPTIONS_COMMENT`: **short-issue-pattern, new-line-hard-break**: Customize render options for different contexts.
-  means a single newline character between paragraphs will cause a line break and adding
+  Set to "none" to disable the defaults, or use comma separated list:
-  trailing whitespace to paragraphs is not necessary to force a line break.
+  - short-issue-pattern: recognized "#123" issue reference and render it as a link to the issue
-- `ENABLE_HARD_LINE_BREAK_IN_DOCUMENTS`: **false**: Render soft line breaks as hard line breaks in documents, which
+  - new-line-hard-break: render soft line breaks as hard line breaks, which means a single newline character between
-  means a single newline character between paragraphs will cause a line break and adding
+    paragraphs will cause a line break and adding trailing whitespace to paragraphs is not
-  trailing whitespace to paragraphs is not necessary to force a line break.
+    necessary to force a line break.
+- `RENDER_OPTIONS_WIKI`: **short-issue-pattern**: see also RENDER_OPTIONS_COMMENT
+- `RENDER_OPTIONS_REPO_FILE`: **_empty_**: see also RENDER_OPTIONS_COMMENT
 - `CUSTOM_URL_SCHEMES`: Use a comma separated list (ftp,git,svn) to indicate additional
   URL hyperlinks to be rendered in Markdown. URLs beginning in http and https are
   always displayed. If this entry is empty, all URL schemes are allowed
-- `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: List of file extensions that should be rendered/edited as Markdown. Separate the extensions with a comma. To render files without any extension as markdown, just put a comma.
+- `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: List of file extensions that should be rendered/edited as Markdown.
+  Separate the extensions with a comma. To render files without any extension as markdown, just put a comma.
 - `ENABLE_MATH`: **true**: Enables detection of `$...$`, `$$...$$`, ``` $`...`$$ ``` blocks as math blocks.
+- `MATH_CODE_BLOCK_DETECTION`: **inline-dollar,block-dollar**: Enable delimiters for math code block detection.
+  Set to "none" to disable all, or use comma separated list: inline-dollar, inline-parentheses, block-dollar, block-square-brackets.
+  Default value follows GitHub.
 
 ## Server (`server`)
 

docs/usage/markdown.md

@@ -0,0 +1,78 @@
+---
+date: "2025-04-05T00:00:00+08:00"
+slug: "markdown"
+---
+
+# Markdown rendering
+
+Gitea supports most of GitHub markdown features:
+
+- [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)
+
+## 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`
+
+## 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.
+
+To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax. 
+
+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.
+
+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
+
+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
+```
+````