Skip to content
All posts
7 min read
markdown
gitlab
glfm
devops
guide

GitLab Markdown (GLFM): Complete Formatting Guide for Issues & Docs (2026)

Master GitLab Flavored Markdown — issues, merge requests, wikis, task lists, Mermaid, math, cross-references, alerts, and differences from GitHub GFM.

GitLab Flavored Markdown (GLFM) is the markup language behind every GitLab issue, merge request, wiki page, snippet, and repository Markdown file. It builds on CommonMark and GitHub Flavored Markdown, then adds GitLab-specific cross-references, math, diagrams, and inline extensions you will not find on GitHub.

Teams on GitLab — especially in regulated enterprises and self-managed deployments — need GLFM fluency the same way GitHub teams need GFM. Paste GitHub README syntax into GitLab and most of it works; miss GLFM-specific features and you leave collaboration tooling on the table.

This guide covers everything GLFM supports, how it differs from GitHub, and workflows for issues, MRs, and wikis.

Where GLFM applies

GitLab renders GLFM in:

SurfaceFull GLFM
Issue descriptions & comments✅
Merge request descriptions & comments✅
Epics (Premium/Ultimate)✅
Milestone descriptions✅
Wiki pages✅
Snippets (.md extension)✅
Repository Markdown files✅
Release descriptions✅
Issue/MR titles❌ partial

Titles support only: emoji shortcodes, autolinks, #123, @user, !456 — not bold, headings, or code spans. Write plain text titles.

GLFM = CommonMark + GFM + GitLab extensions

From GFM (works like GitHub)

# Heading

**bold** and *italic* and ~~strikethrough~~

- [ ] Task list item
- [x] Completed task

| Col A | Col B |
| ----- | ----- |
| 1     | 2     |

> [!note]
> GFM-style alerts render on GitLab.

[^1]: Footnotes work too.[^1]

````md
```mermaid
flowchart LR
  Issue --> MR --> Deploy
See [CommonMark vs GFM](/blog/commonmark-vs-gfm-guide) for the shared baseline.

### GitLab-specific extensions

| Feature | Syntax | Purpose |
| ------- | ------ | ------- |
| Issue reference | `#123` | Link to issue 123 |
| MR reference | `!456` | Link to merge request 456 |
| Epic reference | `&123` | Link to epic (tier-dependent) |
| User mention | `@username` | Notify user |
| Label reference | `~bug` | Link to label |
| Milestone | `%Backlog` | Link to milestone |
| Snippet | `$snippet-id` | Embed snippet |
| Version | `[+label+v1.0+]` | Version badge |
| Math (KaTeX) | `$inline$` and `$$block$$` | Equations |
| Inline footnote | `^[inline note]` | GLFM-only |
| Colors | `<span style="color:red">` | Limited HTML |

## Cross-references — GLFM's killer feature

Link work across the GitLab instance without full URLs:

```md
Closes #42
Related to #38 and !12
/cc @lead-dev

See also &5 for the epic tracking this initiative.
```

### Closing issues from merge requests

In MR description:

```md
Closes #10, #11, #12
Fixes #15
Resolves #20
```

On merge, GitLab closes referenced issues automatically — Markdown as workflow automation.

### Mention etiquette

```
@username — notifies the user (use sparingly)
/cc @team-lead — common shorthand in comments
```

Avoid `@all` equivalent spam — GitLab has group mention limits.

## Task lists in issues

```md
## Release checklist

- [ ] Update CHANGELOG
- [ ] Run migration
- [x] Security scan passed
- [ ] Deploy to staging
```

Task lists are **clickable** in issues and MRs — checking boxes updates the description live. Pair with [GFM checklist tool](/tools/markdown-gfm-checklist) for local validation before paste.

## Mermaid diagrams

Identical fence syntax to GitHub:

````md
```mermaid
sequenceDiagram
  Dev->>GitLab: Push branch
  GitLab->>CI: Run pipeline
  CI-->>Dev: Pass
```

Deep dive: Mermaid Markdown guide.

Math with KaTeX

Inline:

The complexity is $O(n \log n)$.

Block:

$$
\int_0^1 f(x) dx
$$

GitLab renders math natively — no extension required. GitHub README math is more limited — GLFM wins for technical wikis.

Audit delimiters with math inventory.

Code blocks and syntax highlighting

```ruby
def hello
  puts "GitLab"
end
```

GLFM highlights 100+ languages in issues and repos. Include the language tag — bare fences work but miss colors.

Suggested changes (MR review)

In MR diffs, GitLab supports suggested changes syntax (not standard Markdown):

```suggestion
new_line_of_code
```

Reviewers propose inline edits — powerful for code review, separate from prose Markdown.

Tables and alignment

GFM pipe tables with alignment row:

| Endpoint | Method | Auth |
| :------- | :----: | :---: |
| /render  | POST   | ✅    |
| /health  | GET    | ❌    |

Build in table generator. GitLab accessibility guidance: no empty cells — use N/A or None.

Alerts and callouts

GFM alert syntax:

> [!note]
> Informational context.

> [!warning]
> Breaking API change in 17.0.

> [!tip]
> Use `glab` CLI for faster MR creation.

Generate variants in callout generator.

Colors and limited HTML

GLFM allows some inline HTML where GitHub filters aggressively:

<span style="color: red">Critical</span>

Use sparingly — colors may not meet accessibility contrast requirements. Prefer alerts for emphasis.

Wikis vs. repository docs

ApproachBest for
WikiRunbooks, meeting notes, editable without MR
Repo docs/Versioned with code, MR review, CI lint
GitLab PagesPublished static site from repo

Wiki pages support full GLFM but live outside branch workflow. For docs-as-code, prefer docs/ in the repository with CI validation.

Snippets

Name snippets with .md extension for GLFM rendering:

# API Quickstart

curl -H "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.example.com/api/v4/projects"

Reference in issues: $snippet_id embeds content.

GLFM vs. GitHub GFM — practical differences

FeatureGitLab GLFMGitHub GFM
#issue refs✅✅ (GitHub issues)
!MR refs✅❌ (different syntax)
@user mention✅✅
~label✅❌
Math KaTeX✅ nativelimited
Inline footnotes ^[]✅❌
Mermaid✅✅
Task lists in comments✅ clickable✅ clickable
Emoji :shortcode:✅✅
H6 headings✅✅

Migration tip: GitHub READMEs mostly paste into GitLab verbatim. Add # / ! cross-refs where GitHub used full URLs.

Accessibility (GitLab official guidance)

GitLab documents accessibility expectations for GLFM:

  1. One H1 per page — do not skip heading levels.
  2. Tables — no empty cells; meaningful headers.
  3. Images — descriptive alt text; avoid "image of" phrasing.
  4. Links — descriptive anchor text, not "click here."

Run heading audit before publishing wiki overhauls.

Preview and local editing

GitLab's web UI has Preview on every Markdown field — use it before save.

Local workflow:

  1. Draft in VS Code with GitLab Workflow extension.
  2. Preview in browser editor for GFM parity.
  3. Paste into issue/MR or commit to docs/.

For self-managed instances, confirm your GitLab version — GLFM features expand each release (official GLFM docs).

CI validation for GitLab repos

# .gitlab-ci.yml
validate-docs:
  script:
    - |
      for f in docs/**/*.md; do
        curl -sf -X POST https://trymarkdownviewer.com/api/v1/audit/gfm \
          -H "Authorization: Bearer $MDV_API_KEY" \
          -H "Content-Type: application/json" \
          -d "{\"markdown\": $(jq -Rs . < "$f")}"
      done
  rules:
    - changes:
        - docs/**/*

Also: extract links, audit readme score for root README.

Common GLFM mistakes

1. Markdown in issue titles. Bold and code do not render — plain text only.

2. Assuming GitHub MR syntax. Use !123 for merge requests, not GitHub's pull patterns.

3. Empty table cells. GitLab accessibility lint fails; use N/A.

4. Inline footnotes on shared repos. ^[note] breaks on GitHub — use [^ref] for cross-platform files.

5. Pasting Slack mrkdwn. *bold* means bold in Slack, italic in GLFM — rewrite.

6. Huge Mermaid graphs in issues. Slows page load — link to repo file or wiki instead.

Quick reference

SyntaxPurpose
#123 !456 @user ~label %milestoneCross-references
- [ ] / - [x]Task lists (clickable in issues)
> [!warning]GFM alerts
$equation$ / $$block$$KaTeX math
```mermaid fenceDiagrams
^[inline footnote]GLFM inline footnote
Closes #10Auto-close issues on merge

GLFM is GFM plus the collaboration grammar GitLab teams run on — issue links, MR automation, math, and review-integrated task lists. Learn the cross-reference syntax and your issues stop being isolated text blocks and start being a connected system.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.