GitLab Flavored Markdown (GLFM) development guidelines

<!-- vale gitlab_base.GitLabFlavoredMarkdown = NO -->

This and neighboring pages contain developer guidelines for GitLab Flavored Markdown (GLFM). For the user documentation about Markdown in GitLab, refer to GitLab Flavored Markdown.

GitLab supports Markdown in various places, such as issue or merge request descriptions, comments, and wikis. The Markdown implementation we use is called GitLab Flavored Markdown (GLFM).

CommonMark is the core of GLFM.

...a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification.

Extensions from GitHub Flavored Markdown (GFM), such as tables and task lists, are supported. Various extensions, such as math and multiline blockquotes are then added, creating GLFM.

[!note] In many places in the code, we use gfm or GFM. In those cases, we're usually referring to the Markdown in general, not specifically GLFM.

Basic flow

To create the HTML displayed to the user, the Markdown is usually processed as follows:

• Markdown is read from the user or from the database and given to the backend.
• A processing pipeline (the "Banzai" pipeline) is run.
  • Some pre-processing happens, then is converted into basic HTML using the gitlab-glfm-markdown gem, which uses comrak.
  • Various filters are run which further transform the HTML. For example handling references or custom emoji.
• The HTML is then handed to the frontend, which displays it in various ways, or cached in the database.
  • For example, the rich text editor converts the HTML into a format used by tiptap to be displayed and edited.

Goal

We aim for GLFM to always be 100% compliant with CommonMark. Great pains are taken not to add new syntax unless truly necessary. And in such cases research should be done to find the most acceptable "Markdown" syntax, closely adhering to a common implementation if available. The CommonMark forum is a good place to research discussions on different topics.

Additional resources

• GitLab Flavored Markdown
• Rich text editor development guidelines
• Emojis
• How to render GitLab-flavored Markdown on the frontend?
• Diagrams.net integration

Contact the Plan:Knowledge team if you have any questions.