Commit 172c2d51 authored by Sean McGivern's avatar Sean McGivern

Merge branch 'bw-commonmark-for-files-docs' into 'master'

Update user markdown documentation for CommonMark

See merge request gitlab-org/gitlab-ce!21509
parents 26de39fc dc44b008
......@@ -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/
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment