Skip to content

G
gitlab-ce
Commit 9d742192 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis Committed by Alejandro Rodríguez
Browse files
Options

Merge branch 'docs/markdown' into 'master' 

Remove ToC and fix headings in Markdown docs

See merge request !7523
parent 066ed50a
Show whitespace changes
Inline Side-by-side
Showing with 53 additions and 103 deletions
doc/user/markdown.md
View file @ 9d742192
# Markdown # Markdown
## Table of Contents
**[GitLab Flavored Markdown](#gitlab-flavored-markdown-gfm)**
* [Newlines](#newlines)
* [Multiple underscores in words](#multiple-underscores-in-words)
* [URL auto-linking](#url-auto-linking)
* [Multiline Blockquote](#multiline-blockquote)
* [Code and Syntax Highlighting](#code-and-syntax-highlighting)
* [Inline Diff](#inline-diff)
* [Emoji](#emoji)
* [Special GitLab references](#special-gitlab-references)
* [Task Lists](#task-lists)
* [Videos](#videos)
**[Standard Markdown](#standard-markdown)**
* [Headers](#headers)
* [Emphasis](#emphasis)
* [Lists](#lists)
* [Links](#links)
* [Images](#images)
* [Blockquotes](#blockquotes)
* [Inline HTML](#inline-html)
* [Horizontal Rule](#horizontal-rule)
* [Line Breaks](#line-breaks)
* [Tables](#tables)
* [Footnotes](#footnotes)
**[Wiki-Specific Markdown](#wiki-specific-markdown)**
* [Wiki - Direct page link](#wiki-direct-page-link)
* [Wiki - Direct file link](#wiki-direct-file-link)
* [Wiki - Hierarchical link](#wiki-hierarchical-link)
* [Wiki - Root link](#wiki-root-link)
**[References](#references)**
## GitLab Flavored Markdown (GFM) ## GitLab Flavored Markdown (GFM)
> **Note:** > **Note:**
...@@ -64,7 +26,7 @@ You can use GFM in the following areas: ...@@ -64,7 +26,7 @@ You can use GFM in the following areas:
You can also use other rich text files in GitLab. You might have to install a 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. dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information.
## Newlines ### Newlines
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines
...@@ -84,7 +46,7 @@ Violets are blue ...@@ -84,7 +46,7 @@ Violets are blue
Sugar is sweet Sugar is sweet
## Multiple underscores in words ### Multiple underscores in words
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words
...@@ -99,7 +61,7 @@ perform_complicated_task ...@@ -99,7 +61,7 @@ perform_complicated_task
do_this_and_do_that_and_another_thing do_this_and_do_that_and_another_thing
## URL auto-linking ### URL auto-linking
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#url-auto-linking https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#url-auto-linking
...@@ -120,7 +82,7 @@ GFM will autolink almost any URL you copy and paste into your text: ...@@ -120,7 +82,7 @@ GFM will autolink almost any URL you copy and paste into your text:
* irc://irc.freenode.net/gitlab * irc://irc.freenode.net/gitlab
* http://localhost:3000 * http://localhost:3000
## Multiline Blockquote ### Multiline Blockquote
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote
...@@ -154,7 +116,7 @@ multiple lines, ...@@ -154,7 +116,7 @@ multiple lines,
you can quote that without having to manually prepend `>` to every line! you can quote that without having to manually prepend `>` to every line!
>>> >>>
## Code and Syntax Highlighting ### Code and Syntax Highlighting
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting
...@@ -224,7 +186,7 @@ s = "There is no highlighting for this." ...@@ -224,7 +186,7 @@ s = "There is no highlighting for this."
But let's throw in a <b>tag</b>. But let's throw in a <b>tag</b>.
``` ```
## Inline Diff ### Inline Diff
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff
...@@ -240,7 +202,7 @@ However the wrapping tags cannot be mixed as such: ...@@ -240,7 +202,7 @@ However the wrapping tags cannot be mixed as such:
- {- deletions -] - {- deletions -]
- [- deletions -} - [- deletions -}
## Emoji ### Emoji
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji
...@@ -265,7 +227,7 @@ If you are new to this, don't be :fearful:. You can easily join the emoji :famil ...@@ -265,7 +227,7 @@ If you are new to this, don't be :fearful:. You can easily join the emoji :famil
Consult the [Emoji Cheat Sheet](http://emoji.codes) for a list of all supported emoji codes. :thumbsup: Consult the [Emoji Cheat Sheet](http://emoji.codes) for a list of all supported emoji codes. :thumbsup:
## Special GitLab References ### Special GitLab References
GFM recognizes special references. GFM recognizes special references.
...@@ -305,7 +267,7 @@ GFM also recognizes certain cross-project references: ...@@ -305,7 +267,7 @@ GFM also recognizes certain cross-project references:
| `namespace/project@9ba12248...b19a04f5` | commit range comparison | | `namespace/project@9ba12248...b19a04f5` | commit range comparison |
| `namespace/project~"Some label"` | issues with given label | | `namespace/project~"Some label"` | issues with given label |
## Task Lists ### Task Lists
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists
...@@ -328,7 +290,7 @@ You can add task lists to issues, merge requests and comments. To create a task ...@@ -328,7 +290,7 @@ You can add task lists to issues, merge requests and comments. To create a task
Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes. Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes.
## Videos ### Videos
> If this is not rendered correctly, see > If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos
...@@ -345,9 +307,9 @@ Here's a sample video: ...@@ -345,9 +307,9 @@ Here's a sample video:
![Sample Video](img/markdown_video.mp4) ![Sample Video](img/markdown_video.mp4)
# Standard Markdown ## Standard Markdown
## Headers ### Headers
```no-highlight ```no-highlight
# H1 # H1
...@@ -366,21 +328,6 @@ Alt-H2 ...@@ -366,21 +328,6 @@ Alt-H2
------ ------
``` ```
# H1
## H2
### H3
#### H4
##### H5
###### H6
Alternatively, for H1 and H2, an underline-ish style:
Alt-H1
======
Alt-H2
------
### Header IDs and links ### Header IDs and links
All Markdown-rendered headers automatically get IDs, except in comments. All Markdown-rendered headers automatically get IDs, except in comments.
...@@ -416,7 +363,7 @@ Would generate the following link IDs: ...@@ -416,7 +363,7 @@ Would generate the following link IDs:
Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID. Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID.
## Emphasis ### Emphasis
```no-highlight ```no-highlight
Emphasis, aka italics, with *asterisks* or _underscores_. Emphasis, aka italics, with *asterisks* or _underscores_.
...@@ -436,7 +383,7 @@ Combined emphasis with **asterisks and _underscores_**. ...@@ -436,7 +383,7 @@ Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~ Strikethrough uses two tildes. ~~Scratch this.~~
## Lists ### Lists
```no-highlight ```no-highlight
1. First ordered list item 1. First ordered list item
...@@ -492,7 +439,7 @@ the second list item will be incorrectly labeled as `1`. ...@@ -492,7 +439,7 @@ the second list item will be incorrectly labeled as `1`.
Second paragraph of first item. Second paragraph of first item.
2. Another item 2. Another item
## Links ### Links
There are two ways to create links, inline-style and reference-style. There are two ways to create links, inline-style and reference-style.
...@@ -544,7 +491,8 @@ Relative links do not allow referencing project files in a wiki page or wiki pag ...@@ -544,7 +491,8 @@ Relative links do not allow referencing project files in a wiki page or wiki pag
will point the link to `wikis/style` when the link is inside of a wiki markdown file. will point the link to `wikis/style` when the link is inside of a wiki markdown file.
## Images
### Images
Here's our logo (hover to see the title text): Here's our logo (hover to see the title text):
...@@ -568,7 +516,7 @@ Reference-style: ...@@ -568,7 +516,7 @@ Reference-style:
[logo]: img/markdown_logo.png [logo]: img/markdown_logo.png
## Blockquotes ### Blockquotes
```no-highlight ```no-highlight
> Blockquotes are very handy in email to emulate reply text. > Blockquotes are very handy in email to emulate reply text.
...@@ -586,7 +534,7 @@ Quote break. ...@@ -586,7 +534,7 @@ Quote break.
> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
## Inline HTML ### Inline HTML
You can also use raw HTML in your Markdown, and it'll mostly work pretty well. You can also use raw HTML in your Markdown, and it'll mostly work pretty well.
...@@ -610,7 +558,7 @@ See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubyd ...@@ -610,7 +558,7 @@ See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubyd
<dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd> <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl> </dl>
## Horizontal Rule ### Horizontal Rule
``` ```
Three or more... Three or more...
...@@ -642,7 +590,7 @@ ___ ...@@ -642,7 +590,7 @@ ___
Underscores Underscores
## Line Breaks ### Line Breaks
My basic recommendation for learning how line breaks work is to experiment and discover -- hit &lt;Enter&gt; once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. "Markdown Toggle" is your friend. My basic recommendation for learning how line breaks work is to experiment and discover -- hit &lt;Enter&gt; once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. "Markdown Toggle" is your friend.
...@@ -672,7 +620,7 @@ This line is also a separate paragraph, and... ...@@ -672,7 +620,7 @@ This line is also a separate paragraph, and...
This line is on its own line, because the previous line ends with two This line is on its own line, because the previous line ends with two
spaces. spaces.
## Tables ### Tables
Tables aren't part of the core Markdown spec, but they are part of GFM and Markdown Here supports them. Tables aren't part of the core Markdown spec, but they are part of GFM and Markdown Here supports them.
...@@ -708,16 +656,15 @@ By including colons in the header row, you can align the text within that column ...@@ -708,16 +656,15 @@ By including colons in the header row, you can align the text within that column
| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | | Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 |
| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | | Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 |
## Footnotes ### Footnotes
You can add footnotes to your text as follows.[^1]
[^1]: This is my awesome footnote.
``` ```
You can add footnotes to your text as follows.[^1] You can add footnotes to your text as follows.[^2]
[^1]: This is my awesome footnote. [^2]: This is my awesome footnote.
``` ```
You can add footnotes to your text as follows.[^2]
## Wiki-specific Markdown ## Wiki-specific Markdown
The following examples show how links inside wikis behave. The following examples show how links inside wikis behave.
...@@ -792,13 +739,16 @@ A link starting with a `/` is relative to the wiki root. ...@@ -792,13 +739,16 @@ A link starting with a `/` is relative to the wiki root.
```markdown ```markdown
[Link to Related Page](/miscellaneous.md) [Link to Related Page](/miscellaneous.md)
``` ```
## References ## References
- This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). - 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. - 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. - [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown.
[^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.
[markdown.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md [markdown.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md
[rouge]: http://rouge.jneen.net/ "Rouge website" [rouge]: http://rouge.jneen.net/ "Rouge website"
[redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website" [redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website"
[^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7