GitLab Flavored Markdown (GLFM) | GitLab Docs
/ GitLab Flavored Markdown (GLFM) Tier : Free, Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated GitLab Flavored Markdown (GLFM) is a markup language that formats text in the GitLab user interface. GLFM: Creates rich content with support for code, diagrams, math equations, and multimedia. Links issues, merge requests, and other GitLab content with cross-references. Organizes information with task lists, tables, and collapsible sections.
Supports syntax highlighting for over 100 programming languages. Ensures accessibility with semantic heading structures and image descriptions. When you enter text in the GitLab UI, GitLab assumes the text is in GitLab Flavored Markdown. You can use GitLab Flavored Markdown in: Comments Issues Epics Merge requests Milestones Snippets (the snippet must be named with a .md extension) Wiki pages Markdown documents inside repositories Releases You can also use other rich text files in GitLab.
You might have to install a dependency to do so. For more information, see the gitlab-markup gem project . This Markdown specification is valid for GitLab only. We do our best to render the Markdown faithfully here, however the GitLab documentation website and the GitLab handbook use a different Markdown renderer. To see exact examples of how GitLab renders any of these examples: Copy the relevant raw Markdown example (not the rendered version of the example).
Paste the Markdown somewhere in GitLab that supports Markdown previews, for example issue or merge request comments or descriptions, or a new Markdown file. Select Preview to view the GitLab-rendered Markdown. Differences with standard Markdown GitLab Flavored Markdown consists of the following: Core Markdown features, based on the CommonMark specification . Extensions from GitHub Flavored Markdown . Extensions made specifically for GitLab.
All standard Markdown formatting should work as expected in GitLab. Some standard functionality is extended with additional features, without affecting the standard usage. The following features are not found in standard Markdown: Alerts Color chips written in HEX , RGB , or HSL Description lists Diagrams and flowcharts Emoji Footnotes Front matter GitLab-specific references (Not supported in Markdown snippet files.) Includes Placeholders Inline diffs Math equations and symbols written in LaTeX Strikethrough Table of Contents Tables Task lists Wiki-specific Markdown The following features are extended from standard Markdown: Standard Markdown Extended Markdown in GitLab Blockquotes Multiline blockquotes Code blocks Colored code and syntax highlighting Headings Linkable heading anchors Images Embedded videos and audio Links Automatically linking URLs Markdown and accessibility When you use GitLab Flavored Markdown, you are creating digital content.
This content should be as accessible as possible to your audience. The following list is not exhaustive, but it provides guidance for some of the GitLab Flavored Markdown styles to pay particular attention to: Accessible headings Use heading formatting to create a logical heading structure. The structure of headings on a page should make sense, like a good table of contents. Ensure that there is only one h1 element on a page, that heading levels are not skipped, and that they are nested correctly.
Accessible tables To keep tables accessible and scannable, tables should not have any empty cells. If there is no otherwise meaningful value for a cell, consider entering “N/A” or “None”. Accessible images and videos Describe the image or video in the [alt text] . Make the description accurate, succinct, and unique. Don’t use image of or video of in the description. For more information, see WebAim Alternative Text .
Work item and merge request titles Full GitLab Flavored Markdown support introduced in GitLab 18.0. Full GitLab Flavored Markdown support removed in GitLab 18.11. Titles of issues, merge requests, epics, and other work items do not support full GitLab Flavored Markdown. Titles support only: Code spans ( `code` ), without support for using additional backticks or escaping. Emoji ( :emoji: shortcodes and custom emoji). Auto-linked URLs.
GitLab-specific references like #123 , @user , and !456 . Standard Markdown syntax like bold, italic, links, headings, lists, and other block-level formatting is not processed in titles. For example, the title **Merge request title** is not displayed in bold and is displayed with the asterisks. Headings Create headings from 1 to 6 by using # . markdown # H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 Alternatively, for H1 and H2, use an underline style: markdown Alt-H1 ====== Alt-H2 ------ Heading anchors Heading link generation changed in GitLab 17.0.
GitLab automatically adds an anchor to every Markdown heading, so you can link to it. On hover, a link to those anchors becomes visible to make it easier to copy the link to the heading to use it somewhere else. The anchors are generated from the content of the heading according to the following rules: All text is converted to lowercase. All characters except letters, numbers, hyphens, and underscores are removed. All spaces are converted to hyphens.
If a heading with the same anchor has already been generated, a unique incrementing number is appended, starting at 1. Example: markdown # This heading has spaces in it ## This heading has a :thumbsup: in it # This heading has Unicode in it: 한글 ## This heading has spaces in it ### This heading has spaces in it ## This heading has 3.5 in it (and parentheses) ## This heading has multiple spaces and --- hyphens_and_underscores Would generate the following heading anchors: #this-heading-has-spaces-in-it #this-heading-has-a-thumbsup-in-it #this-heading-has-unicode-in-it-한글 #this-heading-has-spaces-in-it-1 #this-heading-has-spaces-in-it-2 #this-heading-has-35-in-it-and-parentheses #this-heading-has--multiple-spaces-and-----hyphens_and_underscores In a snippet, headings also get a prefix derived from the filename, to prevent anchor collisions across multiple files.
For example, a ## TL;DR heading in a file named README.md gets the anchor #readme-tldr instead of #tldr . Line breaks A line break is inserted (a new paragraph starts) if the previous text is ended with two newlines. For example, when you press Enter twice in a row. If you only use one newline (press Enter once), the next sentence remains part of the same paragraph. Use this approach if you want to keep long lines from wrapping, and keep them editable: markdown Here's a line for us to start with.
This longer line is separated from the one above by two newlines, so it is a *separate paragraph* . This line is also a separate paragraph, but... These lines are only separated by single newlines, so they *do not break* and just follow the previous lines in the *same paragraph* . When rendered, the example looks similar to: Here’s a line for us to start with. This longer line is separated from the one above by two newlines, so it is a separate paragraph .
This line is also a separate paragraph, but… These lines are only separated by single newlines, so they do not break and just follow the previous lines in the same paragraph . Newlines A paragraph is one or more consecutive lines of text, separated by one or more blank lines (two newlines at the end of the first paragraph), as explained in line breaks . Need more control over line breaks or soft returns? Add a single line break by ending a line with a backslash, or two or more spaces.
Two newlines in a row create a new paragraph, with a blank line in between: markdown First paragraph. Another line in the same paragraph. A third line in the same paragraph, but this time ending with two spaces.<space><space> A new line directly under the first paragraph. Second paragraph. Another line, this time ending with a backslash.\ A new line due to the previous backslash. When rendered, the example looks similar to: F
The rest of this page is on the live site.