Add support for GitLab flavored markdown

[remcohaszing]

Subject of the feature

GitLab uses their own flavor of markdown. They call if GitLab Flavored Markdown (GFM). This is basically an extension of GitHub Flavored Markdown (also called GFM).

In addition to the linked specification, they markdown also supports quick actions inside their markdown in some contexts.

Problem

These special syntaxes are not recognized. This causes tooling such as remark-lint and Prettier to not work properly for them.

Expected behavior

All syntaxes, special GitLab references, and slash commands can be recognized.

Alternatives

Avoid using GitLab specific syntax. However, it would be nice if GitLab issue templates can be formatted, linted, and spell checked.

[wooorm]

For the big question, “support all of gitlab-fm”, I’m not really interested in doing that 😅 It’s a lot of work to reverse-engineer something like GFM. I don’t hear a lot of folks wanting it, and I don‘t use it myself. And generally, I’d say it’s wiser to use as few extensions as possible, because it makes the markdown not portable.

What is missing in micromark? What features are not working as expected? E.g., colors chips and diagrams are not changes to the language, but changes in the renderer. Math and frontmatter have separate extensions already.

For quick actions, are you 100% that those are in the language too, and not in the renderer? E.g, mentions on GH are similar, but they are an extension to the renderer. Take for example: \@wooorm (\@wooorm). If it was a markdown construct, the at-sign would be escaped and the mention not work, but it does!

Depending on further information, I would point you to either make your own micromark extensions, or remark plugins. This is fine in userland, or maintained here, but I’m not interested in writing code for it.

[remcohaszing]

I’m not 100% sure which parts are language extensions, and which are part of the renderer.

• emoji
• frontmatter (JSON specific or language annotations)
• inline diff
• [math](https://docs.gitlab.com/ee/user/markdown.html#math
• GitLab references
• Table of Contents
• Multiline blockquote
• Code blocks (Specifically using tildes)
• Footnotes (I think they are just links that are rendered differently)

I avoid GitLab specific syntax, except maybe emoji in issues, not committed files.

The two things that annoy me personally are that given the following issue template:

/estimate 1d
/label Bug

Prettier will format this as:

/estimate 1d /label Bug

This can be avoided by adding an empty line in between actions, so although annoying, it’s not a big deal.

And retext-spell will mark 1d as a spelling error. A workaround is to add 1d to the personal dictionary, but this isn’t very flexible (although this syntax only occurs once per issue template).

I had these small annoyances and hoped you might be interested to support more markdown flavors. Perhaps I’ll look into it some day, but I’ll close the issue for now.

[wooorm]

:+1:

For future reference:

• (g)emoji: are supported by several remark projects too
• frontmatter: all except for custom languages (---php) syntax are supported with remark-frontmatter
• inline diff is not supported, it looks a bit like critic markup btw
• math: a different syntax is supported with remark-math
• references: some of these are the same on GH and supported in remark-github. GH does this on the AST, so a similar project like remark-github could also do it with regexes instead of integrating with the parser
• toc: not supported (remark-toc can generate one for a heading though, which would work everywhere)
• multiline blockquote: not supported
• code blocks w/ tildes: standard commonmark, so already supported
• footnotes: can be done w/ remark-footnotes

---

The slash syntax seems to be something else? “Quick Actions” apparently. Uhmmm. I don’t know what their limitations are. Indeed, loose paragraphs might be fine:

/estimate 1d

/label Bug

And for spelling, you could turn them into some custom node type with a regex based AST traversal project (similar to remark-github, through mdast-util-find-and-replace). Then, remark-retext will ignore it because it’s syntactical and not prose, and thus it won’t be spellchecked!