Skip to content

G
gitlab-ce
Commit a4d6cc3d authored by Marcin Sedlak-Jakubowski's avatar Marcin Sedlak-Jakubowski Committed by Marcia Ramos
Browse files
Options

Apply improvements to markdown page 

- Add docs on the Wiki TOC
- Enhance inline diff section
- Make headings sentence case
- Markdown page Vale style fixes
- Update TOC image name
- Add example to footnote bug
- Write emoji as lowercase
parent ee0c3cc7
Show whitespace changes
Inline Side-by-side
Showing with 87 additions and 52 deletions
doc/user/markdown.md
View file @ a4d6cc3d
......@@ -45,10 +45,10 @@ in October 2018.
You may have older issues, merge requests, or Markdown documents in your
repository that were written using some of the nuances of GitLab's RedCarpet version
of Markdown. Since CommonMark uses a slightly stricter syntax, these documents
may now display a little differently since we've transitioned to CommonMark.
of Markdown. Since CommonMark uses slightly stricter syntax, these documents
might now appear a little differently since we have transitioned to CommonMark.
It is usually quite easy to fix. For example, numbered lists with nested lists may
It's usually quite easy to fix. For example, numbered lists with nested lists may
render incorrectly:
```markdown
......@@ -119,7 +119,7 @@ changing how standard Markdown is used:
> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors).
It is possible to have color written in HEX, RGB or HSL format rendered with a color
It's possible to have color written in HEX, RGB, or HSL format rendered with a color
indicator.
Supported formats (named colors are not supported):
......@@ -154,14 +154,14 @@ Color written inside backticks will be followed by a color "chip":
### Diagrams and flowcharts
It is possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](http://plantuml.com).
It's possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](http://plantuml.com).
#### Mermaid
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) in
GitLab 10.3.
Visit the [official page](https://mermaidjs.github.io/) for more details. If you are new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams.
Visit the [official page](https://mermaidjs.github.io/) for more details. If you're new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams.
In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block:
......@@ -236,7 +236,7 @@ Sometimes you want to :monkey: around a bit and add some :star2: to your :speech
You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that.
If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.
If you're new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.
Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
```
......@@ -247,7 +247,7 @@ Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/ma
You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0">. People will <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0"> you for that.
If you are new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes.
If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes.
Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0">
......@@ -345,7 +345,7 @@ The wrapping tags can be either curly braces or square brackets:
---
However the wrapping tags cannot be mixed:
However, the wrapping tags can't be mixed:
```markdown
- {+ addition +]
......@@ -354,11 +354,24 @@ However the wrapping tags cannot be mixed:
- [- deletion -}
```
If your diff includes words in `` `code` `` font, make sure to escape each bactick `` ` `` with a
backslash `\`, otherwise the diff highlight won't render correctly:
```markdown
- {+ Just regular text +}
- {+ Text with `backticks` inside +}
- {+ Text with escaped \`backticks\` inside +}
```
- {+ Just regular text +}
- {+ Text with `backticks` inside +}
- {+ Text with escaped \`backticks\` inside +}
### Math
> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math).
It is possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX).
It's possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX).
Math written between dollar signs `$` will be rendered inline with the text. Math written
inside a [code block](#code-spans-and-blocks) with the language declared as `math`, will be rendered
......@@ -462,22 +475,35 @@ unordered or ordered lists:
1. [ ] Sub-task 1
1. [x] Sub-task 2
### Table of Contents
### Table of contents
A table of contents can be added to a Markdown file, issue or merge request
description, or a wiki page, by adding the tag `[[_TOC_]]` on its own line.
It will be replaced with an unordered list that links to the various
headers.
You can add a table of contents to a Markdown file, wiki page, or issue/merge request
description, by adding the tag `[[_TOC_]]` on its own line.
It will appear as an unordered list that links to the various headers.
```markdown
This is an intro sentence to my Wiki page.
[[_TOC_]]
## My first heading
First section content.
## My second heading
Second section content.
```
![Preview of an auto-generated TOC in a Wiki](img/markdown_toc_preview_v12_9.png)
---
### Wiki-specific Markdown
The following examples show how links inside wikis behave.
#### Wiki - Direct page link
#### Wiki - direct page link
A link which just includes the slug for a page will point to that page,
_at the base level of the wiki_.
......@@ -488,7 +514,7 @@ This snippet would link to a `documentation` page at the root of your wiki:
[Link to Documentation](documentation)
```
#### Wiki - Direct file link
#### Wiki - direct file link
Links with a file extension point to that file, _relative to the current page_.
......@@ -499,10 +525,10 @@ it would link to `<your_wiki>/documentation/file.md`:
[Link to File](file.md)
```
#### Wiki - Hierarchical link
#### Wiki - hierarchical link
A link can be constructed relative to the current wiki page using `./<page>`,
`../<page>`, etc.
`../<page>`, and so on.
If this snippet was placed on a page at `<your_wiki>/documentation/main`,
it would link to `<your_wiki>/documentation/related`:
......@@ -532,7 +558,7 @@ it would link to `<your_wiki>/documentation/main.md`:
[Link to Related Page](../main.md)
```
#### Wiki - Root link
#### Wiki - root link
A link starting with a `/` is relative to the wiki root.
......@@ -560,7 +586,7 @@ If a functionality is extended, the new option will be listed as a sub-section.
### Blockquotes
Blockquotes are an easy way to highlight information, such as a side-note. It is generated
Blockquotes are an easy way to highlight information, such as a side-note. It's generated
by starting the lines of the blockquote with `>`:
```markdown
......@@ -667,8 +693,8 @@ Tildes are OK too.
GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax
highlighting in code blocks. For a list of supported languages visit the
[Rouge project wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers).
Syntax highlighting is only supported in code blocks, it is not possible to highlight
code when it is inline.
Syntax highlighting is only supported in code blocks, so it's not possible to highlight
code when it's inline.
Blocks of code are fenced by lines with three back-ticks (```` ``` ````) or three tildes (`~~~`), and have
the language identified at the end of the first fence:
......@@ -756,7 +782,7 @@ NOTE: **Note:** Strikethrough is not part of the core Markdown standard, but is
> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words).
It is not usually useful to italicize just _part_ of a word, especially when you're
It's not usually useful to italicize just _part_ of a word, especially when you're
dealing with code and names that often appear with multiple underscores. As a result,
GFM extends the standard Markdown standard by ignoring multiple underlines in words,
to allow better rendering of Markdown documents discussing code:
......@@ -793,7 +819,8 @@ do*this*and*do*that*and*another thing
Footnotes add a link to a note that will be rendered at the end of a Markdown file.
To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with the note content.
To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with
the note content.
Regardless of the tag names, the relative order of the reference tags determines the rendered numbering.
......@@ -804,20 +831,23 @@ A footnote reference tag looks like this:[^1]
Reference tags can use letters and other characters.[^footnote-note]
[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`)
in your footnote tag name until an
[upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved.
```
Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until
[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_]
A footnote reference tag looks like this:[^1]
[^this-name-has-w]: This won't be rendered, because the name contains "w".
[^1]: This is the contents of a footnote.
[^this-name-has_]: This won be rendered, because the name contains an underscore.
```
Reference tags can use letters and other characters.[^footnote-note]
[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`)
in your footnote tag name until an
[upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved.
Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until
[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_]
[^this-name-has-w]: This won't be rendered, because the name contains "w".
[^this-name-has_]: This won't be rendered, because the name contains an underscore.
### Headers
......@@ -849,7 +879,7 @@ the header to use it somewhere else.
The IDs are generated from the content of the header according to the following rules:
1. All text is converted to lowercase.
1. All non-word text (e.g., punctuation, HTML) is removed.
1. All non-word text (such as punctuation or HTML) is removed.
1. All spaces are converted to hyphens.
1. Two or more hyphens in a row are converted to one.
1. If a header with the same ID has already been generated, a unique
......@@ -875,8 +905,8 @@ Would generate the following link IDs:
1. `this-header-has-spaces-in-it-2`
1. `this-header-has-3-5-in-it-and-parentheses`
Note that the Emoji processing happens before the header IDs are generated, so the
Emoji is converted to an image which is then 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 is then removed from the ID.
### Horizontal Rule
......@@ -966,7 +996,7 @@ Here's a sample audio clip:
> To see the Markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html).
You can also use raw HTML in your Markdown, and it'll usually work pretty well.
You can also use raw HTML in your Markdown, and it will usually work pretty well.
See the documentation for HTML::Pipeline's [SanitizationFilter](https://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant)
class for the list of allowed HTML tags and attributes. In addition to the default
......@@ -992,7 +1022,7 @@ class for the list of allowed HTML tags and attributes. In addition to the defau
---
It is still possible to use Markdown inside HTML tags, but only if the lines containing Markdown
It's still possible to use Markdown inside HTML tags, but only if the lines containing Markdown
are separated into their own lines:
```html
......@@ -1023,7 +1053,7 @@ are separated into their own lines:
</dd>
</dl>
#### Details and Summary
#### Details and summary
> To see the Markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary).
......@@ -1034,7 +1064,7 @@ tags. This is especially useful for collapsing long logs so they take up less sc
```html
<p>
<details>
<summary>Click me to collapse/fold.</summary>
<summary>Click this to collapse/fold.</summary>
These details <em>will</em> remain <strong>hidden</strong> until expanded.
......@@ -1046,7 +1076,7 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded.
<p>
<details>
<summary>Click me to collapse/fold.</summary>
<summary>Click this to collapse/fold.</summary>
These details <em>will</em> remain <strong>hidden</strong> until expanded.
......@@ -1062,7 +1092,7 @@ after the `</summary>` tag and before the `</details>` tag, as shown in the exam
````html
<details>
<summary>Click me to collapse/fold.</summary>
<summary>Click this to collapse/fold.</summary>
These details _will_ remain **hidden** until expanded.
......@@ -1076,7 +1106,7 @@ PASTE LOGS HERE
<!-- Note: The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown will be fine in GitLab -->
<details>
<summary>Click me to collapse/fold.</summary>
<summary>Click this to collapse/fold.</summary>
These details <em>will</em> remain <b>hidden</b> until expanded.
......@@ -1084,10 +1114,10 @@ These details <em>will</em> remain <b>hidden</b> until expanded.
</details>
### Line Breaks
### Line breaks
A line break will be inserted (a new paragraph will start) if the previous text is
ended with two newlines, i.e. you hit <kbd>Enter</kbd> twice in a row. If you only
ended with two newlines, like when you hit <kbd>Enter</kbd> twice in a row. If you only
use one newline (hit <kbd>Enter</kbd> once), the next sentence will be part of the
same paragraph. This is useful if you want to keep long lines from wrapping, and keep
them easily editable:
......@@ -1116,8 +1146,8 @@ in the *same paragraph*.
GFM adheres to the Markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/).
A paragraph is simply one or more consecutive lines of text, separated by one or
more blank lines (i.e. two newlines at the end of the first paragraph), as [explained above](#line-breaks).
A paragraph is one or more consecutive lines of text, separated by one or
more blank lines (two newlines at the end of the first paragraph), as [explained above](#line-breaks).
If you need more control over line-breaks or soft returns, you can add a single line-break
by ending a line with a backslash, or two or more spaces. Two newlines in a row will create a new
......@@ -1340,7 +1370,7 @@ Example:
### Superscripts / Subscripts
CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that
Currently, CommonMark and GFM don't support the superscript syntax ( `x^2` ) that
Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts:
```html
......@@ -1353,7 +1383,7 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>.
### Tables
Tables aren't part of the core Markdown spec, but they are part of GFM.
Tables are not part of the core Markdown spec, but they are part of GFM.
1. The first line contains the headers, separated by "pipes" (`|`).
1. The second line separates the headers from the cells, and must contain three or more dashes.
......@@ -1401,8 +1431,8 @@ to the sides of the "dash" lines in the second row. This will affect every cell
[Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27205) in GitLab 12.7.
If you're working in spreadsheet software (e.g. Microsoft Excel, Google
Sheets, Apple Numbers), you can copy from a spreadsheet, and GitLab will
If you're working in spreadsheet software (for example, Microsoft Excel, Google
Sheets, or Apple Numbers), you can copy from a spreadsheet, and GitLab will
paste it as a Markdown table. For example, suppose you have the
following spreadsheet:
......
doc/user/project/wiki/index.md
View file @ a4d6cc3d
......@@ -93,6 +93,11 @@ To edit a page, simply click on the **Edit** button. From there on, you can
change its content. When done, click **Save changes** for the changes to take
effect.
### Adding a table of contents
To generate a table of contents from the headings in a Wiki page, use the `[[_TOC_]]` tag.
For an example, see [Table of contents](../../markdown.md#table-of-contents).
## Deleting a wiki page
NOTE: **Note:**
......
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