GitLab Markdown: GLFM Syntax Guide

GitLab Markdown, officially GitLab Flavored Markdown (GLFM), is CommonMark plus the GitHub extensions plus a GitLab-only layer. That layer adds references like !123, alerts, KaTeX math, a table of contents tag, colour chips, inline diffs, and front matter. This guide is the one-screen cheat sheet the very long official page lacks, with a GLFM-versus-GFM table and notes on where each feature renders.

What Does GitLab Markdown Add to CommonMark?

GitLab's Markdown documentation describes GLFM as three layers: core CommonMark, the GitHub Flavored Markdown extensions (tables, task lists, strikethrough, autolinks), and extensions made for GitLab. GitLab renders it with the gitlab-glfm-markdown gem, a Ruby wrapper around the Rust parser comrak, so behaviour is consistent across issues, wikis, and files.

The practical effect: everything in the GitHub Markdown cheat sheet works in GitLab unchanged. This post skips those basics and covers only the GitLab-specific layer. If you're moving a README from GitHub, it renders the same; the differences appear when you start using references, alerts, and math.

GLFM Cheat Sheet

The table lists each GitLab-only construct, the syntax, and where it renders. "Everywhere" means issues, merge requests, comments, wiki pages, and .md files in a repository. Snippet files are the exception the docs call out for references.

Feature	Syntax	Renders in
Issue reference	#123, GL-123, [issue:123]	Everywhere except snippet files
Merge request	!123	Same
Epic	&123 or [epic:123]	Same
Label	~bug, ~"feature request"	Same
Milestone	%v1.23, %"release candidate"	Same
Snippet	$123	Same
User or group	@user_name, @group_name, @all	Same
Commit	9ba12248, range 9ba12248...b19a04f5	Same
Cross-project	namespace/project#123, project!123	Same
Alert	> [!note] plus tip, important, caution, warning	Any Markdown text box
Table of contents	[[_TOC_]] or [TOC] on its own line	Files, wikis, issues, MRs, epics; not comments
Inline math	$a^2+b^2=c^2$ or $`a^2`$	Everywhere (KaTeX)
Block math	$$...$$ or a ```math fence	Everywhere
Inline diff	{+ added +}, [- removed -]	Everywhere
Colour chip	`#FF0000`, `RGB(0,255,0)`, `HSL(540,70%,50%)`	GitLab UI only
Description list	term on one line, : description below	Everywhere (GitLab 17.7+)
Footnote	[^1] and [^1]: text	Everywhere
Front matter	--- YAML, +++ TOML, or ;;; JSON at the top	Files and wikis only
Include	::include{file=chapter1.md}	Files and wikis only (17.7+)
Wiki link	[[Home]], [[Title|page-slug]]	Wikis
Diagrams	```mermaid, ```plantuml, Kroki fences	Everywhere
Collapsible section	<details><summary> HTML	Everywhere

Description lists are the newest addition and the easiest to miss. Put the term on one line and each description on the next, starting with a colon. GitLab 17.7 or later renders a <dl> block:

Fruits
: apple
: orange

Two details worth knowing from the docs. First, #123 links the issue and \#123 prints it literally, which matters in changelogs that quote ticket numbers. Second, the TOC tag also fires when written mid-line in single brackets, which GitLab labels as unintended behaviour in issue 359077, so keep [TOC] out of prose.

How Does GitLab Markdown Differ From GitHub Markdown?

Both flavours share CommonMark and the GFM extensions, so the difference is what each platform layers on top. Here's the side-by-side for the features people trip over when they switch.

Feature	GitHub (GFM)	GitLab (GLFM)
Alerts	> [!NOTE] and four others	> [!note] and four others, plus a custom title on the same line
Math	$...$, $$...$$, ```math (MathJax)	Same syntax, rendered by KaTeX
Table of contents	None; use the file outline button	[[_TOC_]] or [TOC]
Merge/pull request ref	#123 for both issues and PRs	!123 for MRs, #123 for issues
Inline diff	None	{+ +} and [- -]
Colour chips	None	HEX, RGB, HSL in backticks
Description lists	None	Yes, since 17.7
Front matter	Rendered as a table in .md files	Shown as-is in a box at the top
Includes	None	::include{file=...} in files and wikis
Footnotes	Yes	Yes
Diagrams	Mermaid, GeoJSON, STL	Mermaid, PlantUML, Kroki
Underline	No	No; <ins> is the allowed HTML tag

The alert syntax is the same > [!type] blockquote pattern in both places. The Markdown callout guide explains the rendering and the fallbacks; GitLab's five types are note, tip, important, caution, and warning, introduced in GitLab 17.10. GitHub's docs write the type in upper case and GitLab's in lower case; we haven't tested whether either platform accepts the other's casing.

For the TOC, GitLab is the easier platform: drop [[_TOC_]] on its own line and the headings below it become a linked list. The Markdown table of contents guide covers the manual alternative you need on GitHub.

Where Does GLFM Render Differently?

GLFM behaves differently depending on which text box you're in, and the docs scatter those rules across sections. Grouped by context:

Rendered .md files and wiki pages. These get the full set: front matter, includes, the TOC tag, and no render limit on math. Wikis add their own link syntax, where [[How to use GitLab|how-to-use-gitlab]] links by page slug rather than page title, per the wiki-specific Markdown page.

Issues, merge requests, and epics. References, alerts, math, and the TOC all work in the description field. Front matter and includes do not. GitLab also renders only the first 1,000 inline math instances in these views to prevent abuse, and shows the rest as text.

Comments and notes. Same as issues, minus the TOC. The docs are explicit that a table of contents cannot be added to notes or comments.

Snippet files. Standard Markdown renders, but GitLab-specific references (#123, !123, @user) do not link.

One more difference: the rich text editor can't insert new math blocks or footnotes. Switch to the plain text editor for those, per GitLab issues 366527 and 365265.

GitLab Math, Diffs, and Colour Chips

Three GitLab-only features deserve a full example because their syntax has a twist.

Math uses KaTeX, and GitLab accepts an extra inline form with backticks inside the dollar signs. That form avoids conflicts with currency in the same paragraph:

Inline: $`a^2+b^2=c^2`$ or $a^2+b^2=c^2$

```math
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
```

KaTeX supports a subset of LaTeX; the Markdown equation guide lists what's in and out.

Inline diffs mark changes inside prose, useful in a merge request comment that suggests wording:

- {+ addition +}
- [- deletion -]

You can't mix bracket styles ({+ text +] fails), and the highlighting doesn't work inside code spans. Colour chips need no special syntax at all. Write #FF0000, RGB(0,255,0), or HSLA(540,70%,50%,0.3) in backticks and the GitLab UI draws a swatch next to the code. The docs state that named colours such as red are not supported.

Try the CommonMark Parts of GLFM

The GitLab-only constructs (references, alerts, TOC, chips) need GitLab itself, or the GLFM dingus that the gem project publishes. Everything else in a GitLab file is CommonMark plus GFM, and that part renders in our editor. The sample below mixes both so you can see which lines come through.

When the file is a README, run it through the Markdown formatter first so the tables line up before you push.

GitLab Markdown Underline and Styling Limits

"GitLab markdown underline" is a common search and the honest answer is that GLFM has no underline syntax. Underscores are emphasis, not underline. GitLab's inline HTML rules point to the html-pipeline sanitization allowlist, which permits ins but not u and strips every style attribute. So <ins>underlined</ins> renders with the browser's default underline, and <u> and <span style="text-decoration: underline"> both lose their effect.

The same allowlist explains the "gitlab markdown css" question: there's no way to attach a class or inline style in issues, wikis, or rendered files. GitLab adds span, abbr, details, and summary to the default list, which is enough for collapsible sections and abbreviations. For anything that needs real styling, GitLab Pages with your own HTML is the route. The Markdown underline workarounds post covers the other platforms.

Common GLFM Mistakes

Using #123 for a merge request. On GitHub, issues and pull requests share one number space. On GitLab they don't: #123 is an issue and !123 is a merge request. A wrong prefix links to the wrong object or nothing.

Putting front matter in an issue description. The --- block only counts as front matter in .md files and wiki pages. In an issue it renders as a horizontal rule followed by plain text.

Expecting [TOC] to work in a comment. It doesn't. The tag works in file, wiki, issue, MR, and epic descriptions, not in notes. Write a manual list of links there.

GitLab Markdown FAQ

Treat GitLab Markdown as GFM with a GitLab-only layer on top. Learn the reference prefixes, drop [[_TOC_]] into long descriptions, and remember that front matter and includes belong to files and wikis alone. Draft the CommonMark parts in the editor, then paste into GitLab to check the references and alerts before you save.