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:
| Surface | Full 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
| Approach | Best for |
|---|---|
| Wiki | Runbooks, meeting notes, editable without MR |
Repo docs/ | Versioned with code, MR review, CI lint |
| GitLab Pages | Published 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
| Feature | GitLab GLFM | GitHub GFM |
|---|---|---|
#issue refs | ✅ | ✅ (GitHub issues) |
!MR refs | ✅ | ❌ (different syntax) |
@user mention | ✅ | ✅ |
~label | ✅ | ❌ |
| Math KaTeX | ✅ native | limited |
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:
- One H1 per page — do not skip heading levels.
- Tables — no empty cells; meaningful headers.
- Images — descriptive alt text; avoid "image of" phrasing.
- 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:
- Draft in VS Code with GitLab Workflow extension.
- Preview in browser editor for GFM parity.
- 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.
Related articles
- GitHub README guide — closest cousin to GLFM
- CommonMark vs GFM — shared foundation
- Mermaid guide — diagrams in issues
- Docs-as-code guide — repo-based docs
- Markdown footnotes guide —
[^1]vs^[inline]
Quick reference
| Syntax | Purpose |
|---|---|
#123 !456 @user ~label %milestone | Cross-references |
- [ ] / - [x] | Task lists (clickable in issues) |
> [!warning] | GFM alerts |
$equation$ / $$block$$ | KaTeX math |
```mermaid fence | Diagrams |
^[inline footnote] | GLFM inline footnote |
Closes #10 | Auto-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.
Ship documentation from Git with Markdown — repo structure, Hugo, Docusaurus, MDX, review workflows, CI linting, API automation, and patterns documentation teams use at scale.
A power-user tutorial for advanced Markdown tasks — diffing revisions, validating Mermaid, redacting secrets, normalizing structure, merging and splitting docs, and managing footnotes.
A layered strategy for catching Markdown problems — editor checks, a pre-commit hook, and a CI gate on every PR — so broken headings, dead links, and bad tables never reach main.