GitLab Flavored Markdown Official Specification

• Introduction
• GitLab Official Specification Markdown
  • Footnotes
  • Task list items
  • Front matter
  • Table of contents

Introduction

TODO: Write a GitLab-specific version of the GitHub Flavored Markdown intro section.

NOTE: The example numbering in this document does not start at "1", because this official specification only contains a subset of all the examples which are supported by GitLab Flavored Markdown. See snapshot_spec.html for a complete list of all examples, which are a superset of examples from:

• CommonMark
• GitHub Flavored Markdown
• GitLab Flavored Markdown Official Specification (the same ones from this specifiation)
• GitLab Flavored Markdown Internal Extensions.

GitLab Official Specification Markdown

Currently, only some of the GitLab-specific markdown features are listed in this section. We may eventually add all GitLab-specific features currently listed as supported in the user-facing documentation for GitLab Flavored Markdown.

There is currently only this single top-level heading, but the examples may be split into multiple top-level headings in the future.

Footnotes

See the footnotes section of the user-facing documentation for GitLab Flavored Markdown.

footnote reference tag [^fortytwo]

[^fortytwo]: footnote text

<p>
footnote reference tag
<sup>
<a href="#fn-fortytwo-42" id="fnref-fortytwo-42" data-footnote-ref>
1
</a>
</sup>
</p>
<section data-footnotes>
<ol>
<li id="fn-fortytwo-42">
<p>
footnote text
<a href="#fnref-fortytwo-42" data-footnote-backref>
</a>
</p>
</li>
</ol>
</section>

Task list items

See Task lists in the GitLab Flavored Markdown documentation.

Task list items (checkboxes) are defined as a GitHub Flavored Markdown extension in a section above. GitLab extends the behavior of task list items to support additional features. Some of these features are in-progress, and should not yet be considered part of the official GitLab Flavored Markdown specification.

Some of the behavior of task list items is implemented as client-side JavaScript/CSS.

The following are some basic examples; more examples may be added in the future.

Incomplete task:

- [ ] incomplete

<ul>
<li>
<task-button/>
<input type="checkbox" disabled/>
incomplete
</li>
</ul>

Completed task:

- [x] completed

<ul>
<li>
<task-button/>
<input type="checkbox" checked disabled/>
completed
</li>
</ul>

Inapplicable task:

- [~] inapplicable

<ul>
<li>
<task-button/>
<input type="checkbox" data-inapplicable disabled>
<s>
inapplicable
</s>
</li>
</ul>

Inapplicable task in a "loose" list. Note that the <del> tag is not applied to the loose text; it has strikethrough applied with CSS.

- [~] inapplicable

  text in loose list

<ul>
<li>
<p>
<task-button/>
<input type="checkbox" data-inapplicable disabled>
<s>
inapplicable
</s>
</p>
<p>
text in loose list
</p>
</li>
</ul>

Front matter

See Front matter in the GitLab Flavored Markdown documentation.

Front matter is metadata included at the beginning of a Markdown document, preceding the content. This data can be used by static site generators like Jekyll, Hugo, and many other applications.

YAML front matter:

---
title: YAML front matter
---

<pre>
<code>
title: YAML front matter
</code>
</pre>

TOML front matter:

+++
title: TOML front matter
+++

<pre>
<code>
title: TOML front matter
</code>
</pre>

JSON front matter:

;;;
{
  "title": "JSON front matter"
}
;;;

<pre>
<code>
{
  "title": "JSON front matter"
}
</code>
</pre>

Front matter blocks should be inserted at the top of the document:

text

---
title: YAML front matter
---

<p>text</p>
<hr>
<h2>title: YAML front matter</h2>

Front matter block delimiters shouldn’t be preceded by space characters:

 ---
title: YAML front matter
---

<hr>
<h2>title: YAML front matter</h2>

Table of contents

See table of contents in the GitLab Flavored Markdown documentation.

NOTE: Because of this bug (https://gitlab.com/gitlab-org/gitlab/-/issues/359077), we cannot actually include the TOC tag with single brackets in backticks in this Markdown document, otherwise it would render a table of contents inline right here. So, it's been switched to [ + TOC + ] instead. This can be reverted once that bug is fixed.

A table of contents is an unordered list that links to subheadings in the document. Add either the [[_TOC_]] tag or the [ + TOC + ] tag on its own line.

[TOC]

# Heading 1

## Heading 2

<nav>
  <ul>
    <li><a href="#heading-1">Heading 1</a></li>
    <ul>
      <li><a href="#heading-2">Heading 2</a></li>
    </ul>
  </ul>
</nav>
<h1>Heading 1</h1>
<h2>Heading 2</h2>

[[_TOC_]]

# Heading 1

## Heading 2

<nav>
  <ul>
    <li><a href="#heading-1">Heading 1</a></li>
    <ul>
      <li><a href="#heading-2">Heading 2</a></li>
    </ul>
  </ul>
</nav>
<h1>Heading 1</h1>
<h2>Heading 2</h2>

A table of contents is a block element. It should preceded and followed by a blank line.

[[_TOC_]]
text

text
[TOC]

<p>[[<em>TOC</em>]]text</p>
<p>text[TOC]</p>

A table of contents can be indented with up to three spaces.

   [[_TOC_]]

# Heading 1

<nav>
  <ul>
    <li><a href="#heading-1">Heading 1</a></li>
  </ul>
</nav>
<h1>Heading 1</h1>