Support for GitLab Flavored Markdown

[j9ac9k]

Issue opened for a feature request for pandoc to support gitlab flavored markdown.

Language specifics can be found here: https://docs.gitlab.com/ee/user/markdown.html

This feature request comes from this post on the mailing list:
https://groups.google.com/forum/#!msg/pandoc-discuss/MWtpZMW_n70/BMvIOmG8AAAJ

Pandoc has extensions for:

• multiple underscores in words (+intraword_underscores)
• URL auto-linking (+autolink_bare_uris)
• Code and syntax highlighting (+backtick_code_blocks)

Not supported:

• multiline blockquote

• inline diff

• special gitlab references

• task lists

• videos

• special gitlab references

• gitlab's special format for specifying math:

  $`x`$ inline 
  ```math 
   block 
  ``` 
  

[masters3d]

Pandoc 2 introduced a new name for the Github flavored mark down: gfm
Gitlab also calls their version gtm. Gitlab's version is a fork of Github's.

There is PR/MR right now to switch over to Githubs version of common mark.
https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14835/diffs

It would be great if gitlab could provide what is different from the github spec so support could be added to pandadoc.

https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14835#note_45257014

New output format gfm (GitHub-flavored CommonMark) (#3841). This uses bindings to GitHub’s fork of cmark, so it should parse gfm exactly as GitHub does (excepting certain postprocessing steps, involving notifications, emojis, etc.). markdown_github has been deprecated in favor of gfm.

New input format gfm (GitHub-flavored CommonMark) (#3841). This uses bindings to GitHub’s fork of cmark. markdown_github has been deprecated in favor of gfm.

[tarleb]

Regarding task lists: there's now a lua task-list filter which should do the job.

[mb21]

GitLab might also switch over to a CommonMark-compliant variant, see https://gitlab.com/gitlab-org/gitlab-ce/issues/30087

[stragu]

You can follow the process of the switch to CommonMark in this issue: https://gitlab.com/gitlab-org/gitlab-ce/issues/43011
It is currently aimed at being completed for GitLab 11.0, later this month, but not sure how realistic this is.

[lierdakil]

This lua filter may be of interest regarding GitLab's math format.

[mb21]

Gitlab made the switch to a commonmark-based variant, so the list in the first comment of this issue may not be accurate any more.

[j9ac9k]

Am closing this issue as gitlab now used CommonMark

[salim-b]

I still think a dedicated output format for GitLab Flavoured Markdown (I'll call it GLFM since GFM is already occupied) would be very useful.

Currently it doesn't seem possible to accommodate GLFM by just combining Pandoc extensions because

commonmark and gfm have limited support for extensions.

You currently can't combine commonmark+footnotes (which unlike GFM are supported by GLFM) 😞

[alerque]

@j9ac9k I would agree this issue should not be closed, Gitlab's implementation is based on CommonMark for some of the things that could otherwise be ambiguous, but it has lots of things added in after that. Neither commonmark nor gfm are replacements for what glfm does in practice.

[jgm]

When/if we integrate commonmark-hs as pandoc's commonmark reader, it will be possible to be more flexible with extensions, and at that point we could add some GitLab ones.

[j9ac9k]

Thanks folks for following up, reading the comment from @salim-b I agree, this issue should be re-opened. Thanks @jgm for highlighting what the path would look like.

[koocotte]

Can I help on this item? I don't know Haskell but I can produce a list of currently unsupported markup (according to gitlab documentation) and expected result.

[j9ac9k]

@koocotte If you post a task list of the currently unsupported markup in the issue, I'll update the original post to reflect the contents.

[Yash-Singh1]

Just for clarification, Gitlab Flavored Markdown is not a fork of Github Flavored Markdown. Gitlab Flavored Markdown is inspired by Github Flavored Markdown.

[MyriaCore]

Not sure if this will help anyone, but I've been trying to scrape a full setup that closely emulates gitlab markdown, and I came up with this. It's pretty jankey, but it's more meant to be shoved into CI/CD setups than run on your own machine.

[tarleb]

I believe this is mostly solved by the switch to @jgm's new commonmark parser, which allows to choose from a large number of Markdown extensions. The remaining issues seems to be the unsupported math syntax, as well as a possible format shorthand like gfm for convenience.

[salim-b]

Just for reference: I've written a custom R Markdown format for GLFM some time ago: pal::gitlab_document() (sources are here)

Basically, I call Pandoc with the following arguments:

--from=markdown
--to=markdown-smart-simple_tables-multiline_tables-grid_tables-fenced_code_attributes-inline_code_attributes-raw_attribute-pandoc_title_block-yaml_metadata_block
--columns=9999
--standalone

The caveats regarding GFLM syntax unsupported by the above are documented here.

[Yash-Singh1]

I created a blog post comparing Gitlab and GitHub’s markdown syntax: http://www.yashsingh.us/blog/post/gitlab-markdown-vs-github-markdown.md

[seppeon]

GitLab also supports some very useful table formats which enable sorting and filtering of tables:

https://www.youtube.com/watch?v=12yWKw1AdKY