From e3d58503ca45e5f7546fe9e3d422dfd3fda039f8 Mon Sep 17 00:00:00 2001 From: wxiaoguang Date: Sat, 5 Apr 2025 05:08:06 +0000 Subject: [PATCH] Add markdown usage (#198) First simple version Reviewed-on: https://gitea.com/gitea/docs/pulls/198 Reviewed-by: Lunny Xiao Co-authored-by: wxiaoguang Co-committed-by: wxiaoguang --- docs/administration/config-cheat-sheet.md | 20 ++++-- docs/usage/markdown.md | 78 +++++++++++++++++++++++ 2 files changed, 91 insertions(+), 7 deletions(-) create mode 100644 docs/usage/markdown.md diff --git a/docs/administration/config-cheat-sheet.md b/docs/administration/config-cheat-sheet.md index cc391192..4dfd2b73 100644 --- a/docs/administration/config-cheat-sheet.md +++ b/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 - means a single newline character between paragraphs will cause a line break and adding - trailing whitespace to paragraphs is not necessary to force a line break. -- `ENABLE_HARD_LINE_BREAK_IN_DOCUMENTS`: **false**: Render soft line breaks as hard line breaks in documents, which - means a single newline character between paragraphs will cause a line break and adding - trailing whitespace to paragraphs is not necessary to force a line break. +- `RENDER_OPTIONS_COMMENT`: **short-issue-pattern, new-line-hard-break**: Customize render options for different contexts. + Set to "none" to disable the defaults, or use comma separated list: + - short-issue-pattern: recognized "#123" issue reference and render it as a link to the issue + - new-line-hard-break: render soft line breaks as hard line breaks, which means a single newline character between + paragraphs will cause a line break and adding trailing whitespace to paragraphs is not + 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`) diff --git a/docs/usage/markdown.md b/docs/usage/markdown.md new file mode 100644 index 00000000..a1c9e739 --- /dev/null +++ b/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 ``, `` and `