GitLab Flavored Markdown (GLFM) | GitLab Docs Skip to main content Go to GitLab Docs homepage What's new? What's new? Get free trial Toggle menu * Use GitLab * GitLab Duo * GitLab Orbit * Extend * Install * Administer * Subscribe * Contribute * Solutions Getting started Tutorials Manage your organization Organize work with projects Plan and track work Getting started Tutorials Tutorial: Use GitLab for Scrum Tutorial: Use GitLab for Kanban Work items Labels Iterations Milestones Comments and threads Requirements Time tracking Customer relations (CRM) Wikis Roadmaps Objectives and key results (OKR) Keyboard shortcuts Quick actions Markdown Rich text editor Wiki-specific Markdown AsciiDoc Org mode To-Do List GitLab Query Language (GLQL) Manage authentication and authorization Use Git Manage your code Use CI/CD to build your application Secure your application Deploy and release your application Manage your infrastructure Monitor your application Analyze GitLab usage Release notes Feature support Find your GitLab version * GitLab Docs / * Use GitLab / * Plan and track work / * Markdown Help us learn about your current experience with the documentation. Take the survey . 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 History * 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 # . # H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 Alternatively, for H1 and H2, use an underline style: Alt-H1 ====== Alt-H2 ------ Heading anchors History * 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: # 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: 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: 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: First paragraph. Another line in the same paragraph. A third line in the same paragraph, but this time ending with two spaces. 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. This syntax adheres to the Markdown specification for handling paragraphs and line breaks . Emphasis You can emphasize text in multiple ways. Use italics, bold, strikethrough, or combine these emphasis styles together. Examples: Emphasis, or italics, with *asterisks* or _underscores_ . Strong emphasis, or bold, with double **asterisks** or __underscores__ . Combined emphasis with **asterisks and _underscores_** . Strikethrough with double tildes. ~~Scratch this.~~ When rendered, the example looks similar to: Emphasis, or italics, with asterisks or underscores . Strong emphasis, or bold, with double asterisks or underscores . Combined emphasis with asterisks and underscores . Strikethrough with double tildes. Scratch this. Mid-word emphasis Avoid italicizing a portion of a word, especially when you re dealing with code and names that often appear with multiple underscores. GitLab Flavored Markdown ignores multiple underlines in words, to allow better rendering of Markdown documents discussing code: perform_complicated_task do_this_and_do_that_and_another_thing but_emphasis is_desired _here_ When rendered, the example looks similar to: perform_complicated_task do_this_and_do_that_and_another_thing but_emphasis is_desired here If you wish to emphasize only a part of a word, it can still be done with asterisks: perform*complicated*task do*this*and*do*that*and*another thing When rendered, the example looks similar to: perform complicated task do this and do that and another thing Inline diff With inline diff tags, you can display {+ additions +} or [- deletions -] . The wrapping tags can be either curly braces or square brackets: - {+ addition 1 +} - [+ addition 2 +] - {- deletion 3 -} - [- deletion 4 -] However, you cannot mix the wrapping tags: - {+ addition +] - [+ addition +} - {- deletion -] - [- deletion -} Diff highlighting doesn t work with `inline code` . If your text includes backticks ( ` ), escape each backtick with a backslash \ : - {+ Just regular text +} - {+ Text with `backticks` inside +} - {+ Text with escaped \`backticks\` inside +} Horizontal rule Create a horizontal rule by using three or more hyphens, asterisks, or underscores: --- ** * ___ When rendered, all horizontal rules look similar to: Lists You can create ordered and unordered lists. For an ordered list, add the number you want the list to start with, like 1. , followed by a space, at the start of each line. After the first number, it does not matter what number you use. Ordered lists are numbered automatically by vertical order, so repeating 1. for all items in the same list is common. If you start with a number other than 1. , it uses that as the first number, and counts up from there. Examples: 1. First ordered list item 2. Another item - Unordered sub-list. 1. Actual numbers don't matter, just that it's a number 1. Ordered sub-list 1. Next ordered sub-list item 4. And another item. When rendered, the example looks similar to: * First ordered list item * Another item * Unordered sub-list. * Actual numbers don t matter, just that it s a number * Ordered sub-list * Next ordered sub-list item * And another item. For an unordered list, add a - , * , or + , followed by a space, at the start of each line. Don t mix the characters in the same list. Unordered lists can: - use - minuses They can also: * use * asterisks They can even: + use + pluses When rendered, the example looks similar to: Unordered lists can: * use * minuses They can also: * use * asterisks They can even: * use * pluses If a list item contains multiple paragraphs, each subsequent paragraph should be indented to the same level as the start of the list item text. Example: 1. First ordered list item Second paragraph of first item. 1. Another item When rendered, the example looks similar to: * First ordered list item Second paragraph of first item. * Another item If the first item s paragraph isn t indented with the proper number of spaces, the paragraph appears outside the list. Use the correct number of spaces to properly indent under the list item. For example: 1. First ordered list item (Misaligned paragraph of first item.) 1. Another item When rendered, the example looks similar to: * First ordered list item (Misaligned paragraph of first item.) * Another item Ordered lists that are the first sub-item of an unordered list item must have a preceding blank line if they don t start with 1. . For example, with a blank line: - Unordered list item 5. First ordered list item When rendered, the example looks similar to: * Unordered list item * First ordered list item If the blank line is missing, the second list item renders as part of the first one: - Unordered list item 5. First ordered list item When rendered, the example looks similar to: * Unordered list item 5. First ordered list item CommonMark ignores blank lines between ordered and unordered list items, and considers them part of a single list. The items are rendered as a loose list. Each list item is enclosed in a paragraph tag and therefore has paragraph spacing and margins. This makes the list look like there is extra spacing between each item. For example: - First list item - Second list item - A different list When rendered, the example looks similar to: * First list item * Second list item * A different list CommonMark ignores the blank line and renders this as one list with paragraph spacing. Description lists History * Description lists introduced in GitLab 17.7. A description list is a list of terms with corresponding descriptions. Each term can have multiple descriptions. In HTML this is represented with <dl> , <dt> , and <dd> tags. To create a description list, place the term on one line, with the description on the next line beginning with a colon. Fruits : apple : orange Vegetables : broccoli : kale : spinach You can also have a blank line between the term and description. Fruits : apple : orange The rich text editor does not support inserting new description lists. To insert a new description list, use the plain text editor. For more information, see issue 535956 . Task lists You can add task lists anywhere Markdown is supported. * In issues, merge requests, epics, and comments, you can select the boxes. * In all other places, you cannot select the boxes. You must edit the Markdown manually by adding or removing an x in the brackets. Besides complete and incomplete, tasks can also be inapplicable. Selecting an inapplicable checkbox in an issue, merge request, epic, or comment has no effect. To create a task list, follow the format of an ordered or unordered list: - [x] Completed task - [~] Inapplicable task - [ ] Incomplete task - [x] Sub-task 1 - [~] Sub-task 2 - [ ] Sub-task 3 1. [x] Completed task 1. [~] Inapplicable task 1. [ ] Incomplete task 1. [x] Sub-task 1 1. [~] Sub-task 2 1. [ ] Sub-task 3 You can also add task lists to table cells . Links You can create links in multiple ways: - This line shows an [ inline-style link ]( https://example.com ) - This line shows a [ link to a repository file in the same directory ]( permissions.md ) - This line shows a [ relative link to a file one directory higher ]( ../_index.md ) - This line shows a [ link that also has title text ]( https://example.com "This link takes you to Example!" ) When rendered, the examples look similar to: * This line shows an inline-style link * This line shows a link to a repository file in the same directory * This line shows a relative link to a file one directory higher * This line shows a link that also has title text You cannot use relative links to reference project files in a wiki page, or a wiki page in a project file. This limitation exists because wikis are always in separate Git repositories in GitLab. For example, [I'm a reference-style link](style) points to wikis/style only when the link is inside a wiki Markdown file. For more information, see Wiki-specific Markdown . Use heading anchors to link to a specific section in a page: - This line links to [ a section on a different Markdown page, using a `#` and the heading anchor ]( permissions.md#project-permissions ) - This line links to [ a different section on the same page, using a `#` and the heading anchor ]( #heading-anchors ) When rendered, the exampl