Update user markdown documentation for CommonMark
This commit is contained in:
parent
26de39fc64
commit
dc44b0083c
|
@ -7,13 +7,13 @@
|
|||
> this document currently work on our documentation website.
|
||||
>
|
||||
> For the best result, we encourage you to check this document out as rendered
|
||||
by GitLab: [markdown.md]
|
||||
> by GitLab: [markdown.md]
|
||||
|
||||
_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. Previous content, wiki pages and Markdown files (`.md`) in the repositories are still processed using the [Redcarpet Ruby library][redcarpet]._
|
||||
_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the [Redcarpet Ruby library][redcarpet]._
|
||||
|
||||
_Where there are significant differences, we will try to call them out in this document._
|
||||
|
||||
GitLab uses "GitLab Flavored Markdown" (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/).
|
||||
GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/).
|
||||
|
||||
You can use GFM in the following areas:
|
||||
|
||||
|
@ -22,18 +22,46 @@ You can use GFM in the following areas:
|
|||
- merge requests
|
||||
- milestones
|
||||
- snippets (the snippet must be named with a `.md` extension)
|
||||
- wiki pages (currently only rendered by Redcarpet)
|
||||
- markdown documents inside the repository (currently only rendered by Redcarpet)
|
||||
- wiki pages
|
||||
- markdown documents inside the repository
|
||||
|
||||
You can also use other rich text files in GitLab. You might have to install a
|
||||
dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information.
|
||||
|
||||
### Transitioning to CommonMark
|
||||
|
||||
You may have Markdown documents in your repository that were written using some of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a slightly stricter syntax, these documents may now display a little strangely since we've transitioned to CommonMark. Numbered lists with nested lists in particular can be displayed incorrectly.
|
||||
|
||||
It is usually quite easy to fix. In the case of a nested list such as this:
|
||||
|
||||
```markdown
|
||||
1. Chocolate
|
||||
- dark
|
||||
- milk
|
||||
```
|
||||
|
||||
simply add a space to each nested item:
|
||||
|
||||
```markdown
|
||||
1. Chocolate
|
||||
- dark
|
||||
- milk
|
||||
```
|
||||
|
||||
In the documentation below, we try to highlight some of the differences.
|
||||
|
||||
If you have a need to view a document using RedCarpet, you can add the token `legacy_render=1` to the end of the url, like this:
|
||||
|
||||
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md?legacy_render=1
|
||||
|
||||
If you have a large volume of Markdown files, it can be tedious to determine if they will be displayed correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) tool (not an officially supported product) to generate a list of files and differences between how RedCarpet and CommonMark render the files. It can give you a great idea if anything needs to be changed - many times nothing will need to changed.
|
||||
|
||||
### Newlines
|
||||
|
||||
> If this is not rendered correctly, see
|
||||
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines
|
||||
|
||||
GFM honors the markdown specification in how [paragraphs and line breaks are handled](https://daringfireball.net/projects/markdown/syntax#p).
|
||||
GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec].
|
||||
|
||||
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.
|
||||
Line-breaks, or soft returns, are rendered if you end a line with two or more spaces:
|
||||
|
@ -979,8 +1007,9 @@ A link starting with a `/` is relative to the wiki root.
|
|||
## References
|
||||
|
||||
- This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
|
||||
- The [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown.
|
||||
- [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown.
|
||||
- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown.
|
||||
- The detailed specification for CommonMark can be found in the [CommonMark Spec][commonmark-spec]
|
||||
- The [CommonMark Dingus](http://try.commonmark.org) is a handy tool for testing CommonMark syntax.
|
||||
|
||||
[^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com
|
||||
[^2]: This is my awesome footnote.
|
||||
|
@ -993,3 +1022,4 @@ A link starting with a `/` is relative to the wiki root.
|
|||
[katex-subset]: https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX "Macros supported by KaTeX"
|
||||
[asciidoctor-manual]: http://asciidoctor.org/docs/user-manual/#activating-stem-support "Asciidoctor user manual"
|
||||
[commonmarker]: https://github.com/gjtorikian/commonmarker
|
||||
[commonmark-spec]: https://spec.commonmark.org/current/
|
||||
|
|
Loading…
Reference in New Issue