From 1a85ffdab83bdf65bbf41e53d8b2c6b2276e0cb8 Mon Sep 17 00:00:00 2001 From: juke Date: Thu, 10 Apr 2025 20:15:37 +0000 Subject: [PATCH] Expand new Usage/Markdown Docu (#203) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As promised in [Gitea Pull #34105](https://github.com/go-gitea/gitea/pull/34105), I wanted to contribute documentation for MarkDown. You were so fast in adding the page that I had to start over my local-only draft 😄 🚀 I'm not sure how you prefer your commits (I'm new to Gitea), so I've split them for simplest review and dropping of unwanted changes. Co-authored-by: Jules Kerssemakers Reviewed-on: https://gitea.com/gitea/docs/pulls/203 Reviewed-by: Lunny Xiao Co-authored-by: juke Co-committed-by: juke --- docs/usage/markdown.md | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) 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 `