diff options
Diffstat (limited to 'doc/user/markdown.md')
| -rw-r--r-- | doc/user/markdown.md | 62 |
1 files changed, 24 insertions, 38 deletions
diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 4bdf72673a1..be6e483aa54 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,28 +1,28 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- # GitLab Markdown -This Markdown guide is **valid only for GitLab's internal Markdown rendering system for entries and files**. +This Markdown guide is **valid only for the GitLab internal Markdown rendering system for entries and files**. It is **not** valid for the [GitLab documentation website](https://docs.gitlab.com) -or [GitLab's main website](https://about.gitlab.com), as they both use +or the [GitLab main website](https://about.gitlab.com), as they both use [Kramdown](https://kramdown.gettalong.org) as their Markdown engine. The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/) for a complete Kramdown reference. -NOTE: **Note:** +NOTE: We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md). ## GitLab Flavored Markdown (GFM) GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/) (which is based on standard Markdown) in several ways to add additional useful functionality. -It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). +It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax). You can use GFM in the following areas: @@ -52,7 +52,7 @@ The documentation website had its [Markdown engine migrated from Redcarpet to Kr 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 +repository that were written using some of the nuances of the GitLab RedCarpet version of Markdown. Since CommonMark uses slightly stricter syntax, these documents might now appear a little differently since we have transitioned to CommonMark. @@ -162,6 +162,7 @@ Color written inside backticks is followed by a color "chip": ### Diagrams and flowcharts It's possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com). +It's also possible to use [Kroki](https://kroki.io) to create a wide variety of diagrams. #### Mermaid @@ -231,6 +232,11 @@ end To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. Read more in [PlantUML & GitLab](../administration/integration/plantuml.md). +#### Kroki + +To make Kroki available in GitLab, a GitLab administrator needs to enable it first. +Read more in the [Kroki integration](../administration/integration/kroki.md) page. + ### Emoji If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji). @@ -347,7 +353,7 @@ The wrapping tags can be either curly braces or square brackets: - [- deletion 4 -] ``` - + --- @@ -369,7 +375,7 @@ backslash `\`, otherwise the diff highlight don't render correctly: - {+ Text with escaped \`backticks\` inside +} ``` - + ### Math @@ -425,7 +431,7 @@ GFM recognizes the following: | merge request | `!123` | `namespace/project!123` | `project!123` | | snippet | `$123` | `namespace/project$123` | `project$123` | | epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | -| vulnerability **(ULTIMATE)** *(1)* | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | +| vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | | label by ID | `~123` | `namespace/project~123` | `project~123` | | one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | | multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | @@ -435,29 +441,11 @@ GFM recognizes the following: | multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | | specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | | commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README)` | | | -| repository file line references | `[README](doc/README#L13)` | | | +| repository file references | `[README](doc/README.md)` | | | +| repository file line references | `[README](doc/README.md#L13)` | | | | [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | -1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/281035) in GitLab 13.6. - - The Vulnerability special references feature is under development but ready for production use. - It is deployed behind a feature flag that is **disabled by default**. - [GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) - can opt to enable it for your instance. - It's disabled on GitLab.com. - - To disable it: - - ```ruby - Feature.disable(:vulnerability_special_references) - ``` - - To enable it: - - ```ruby - Feature.enable(:vulnerability_special_references) - ``` +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. For example, referencing an issue by using `#123` will format the output as a link to issue number 123 with text `#123`. Likewise, a link to issue number 123 will be @@ -471,7 +459,7 @@ In addition to this, links to some objects are also recognized and formatted. So ### Task lists -> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). +If this section is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). You can add task lists anywhere Markdown is supported, but you can only "click" to toggle the boxes if they are in issues, merge requests, or comments. In other @@ -494,7 +482,7 @@ unordered or ordered lists: 1. [x] Sub-task 2 ``` - + ### Table of contents @@ -774,6 +762,7 @@ But let's throw in a <b>tag</b>. There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough, as well as combine these emphasis styles together. +Strikethrough is not part of the core Markdown standard, but is part of GFM. Examples: @@ -795,9 +784,6 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ -NOTE: **Note:** -Strikethrough is not part of the core Markdown standard, but is part of GFM. - #### Multiple underscores in words and mid-word emphasis If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words). @@ -1072,7 +1058,7 @@ are separated into their own lines: ``` <!-- -Note: The example below uses HTML to force correct rendering on docs.gitlab.com, +The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown is fine in GitLab. --> @@ -1124,7 +1110,7 @@ These details <em>remain</em> <strong>hidden</strong> until expanded. Markdown inside these tags is supported as well. -TIP: **Tip:** +NOTE: If your Markdown isn't rendering correctly, try adding `{::options parse_block_html="true" /}` to the top of the page, and add `markdown="span"` to the opening summary tag like this: `<summary markdown="span">`. @@ -1263,7 +1249,7 @@ Do not change to reference style links. Some text to show that the reference links can follow later. -NOTE: **Note:** +NOTE: Relative links do not allow the referencing of project files in a wiki page, or a wiki page in a project file. The reason for this is that a wiki is always in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)` |