diff --git a/docs/usage/markdown.md b/docs/usage/markdown.md index a1c9e739..865bdae1 100644 --- a/docs/usage/markdown.md +++ b/docs/usage/markdown.md @@ -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 ``, `` and `