Markdown and GitLab
The rule the engine follows: the editor is GitLab, the site adapts to it. Where the site cannot match, the construct is declared unsupported rather than rendered differently. Audited against GitLab 15.5.
| Construct | GitLab | Site | Verdict |
|---|---|---|---|
Headings, lists, tables with alignment, task lists, footnotes, ~~strike~~, autolinks | ✓ | ✓ | identical |
Relative links page.md, ./page.md, page.md#anchor | file → file | /page, /page#anchor | rewritten to routes |
README.md | file | / | the front page |
assets/x.pdf | file | /assets/x.pdf | one assets/ folder per repository, mirrored into the site |
| Images with a relative path | relative to the file | relative to the file, optimized | identical; a broken image is broken on both sides, the build does not fail |
| Heading anchors | #heading-text, Cyrillic kept, -1 for duplicates | the same | identical, except headings with & or " — do not link to those |
Emoji :rocket: | ✓ | ✓ | identical |
Mermaid ```mermaid | client-side | client-side, script only on pages with a diagram | identical |
| PlantUML | if the server has it | rendered to SVG (knowledge bases only) | do not use in landing pages |
Code ```python | ✓ | ✓ | identical; a title="x.js" after the language is ignored by GitLab and drawn by the site |
Math $`a^2`$, ```math | KaTeX | SVG, no fonts | identical — the only math syntax |
Math $a^2$, $$…$$ | literal | literal | unsupported |
Alerts > [!note], [!tip], [!important], [!warning], [!caution] | a quote with the marker text | a styled box | accepted difference: GitLab ≥ 17.10 renders them natively, 15.5 degrades to a readable quote |
| Front matter | shown as a yaml block | hidden | accepted; knowledge bases need none |
HTML <details>, <kbd>, <sup>, <sub>, <br>, <div align> | ✓ | ✓ | identical |
HTML <script>, <iframe>, style=, on*=, javascript: | stripped | stripped (in .md; .mdx is code, not content) | identical |
Definition lists, {attrs}, wiki links [[…]] | literal | literal | unsupported |
In one sentence: write as you write in GitLab; the only non-GitLab thing the site adds is the alert box, and it degrades safely in GitLab itself.
How the pipeline achieves this — which plugins rewrite what — is on How it works.