Add support for GitLab flavored Markdown

Created on 31 July 2023, over 1 year ago
Updated 11 September 2024, 3 months ago

Problem/Motivation

Since Drupal is using GitLab for source control, it would be nice to have support for GitLab flavored Markdown as well as GitHub flavor.

Proposed resolution

There doesn't seem to be a GitLab flavor extension for CommonMark, but it looks like the GitHub one could be used as a template for adding one, at least for the main parts of GitLab flavor (there are some tricky bits like diagrams that would probably need additional libraries).

I think the question is should it be proposed as an addition to the main CommonMark library, or an extension to it.

Remaining tasks

  • Write a GitLab flavor library.
  • Add to module.

User interface changes

API changes

Data model changes

Feature request
Status

Active

Version

1.0

Component

Code

Created by

🇮🇪Ireland lostcarpark

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @lostcarpark
  • 🇺🇸United States ultimike Florida, USA
  • 🇺🇸United States volkswagenchick San Francisco Bay Area

    I second this feature request

  • 🇮🇪Ireland lostcarpark

    Here's a list of non-standard Markdown Features supported by Gitlab. I've compared to the list of included extensions in CommonMark, and added links where there appears to be overlap:

    • Color chips written in HEX, RGB or HSL
    • Diagrams and flowcharts
    • Emoji
    • Footnotes -> Footnotes
    • Front matter -> Front Matter
    • GitLab-specific references
    • Inline diffs
    • Math equations and symbols written in LaTeX
    • Strikethrough -> Strikethrough
    • Table of Contents -> Table of Contents
    • Tables -> Tables
    • Task lists -> Task Lists
    • Wiki-specific Markdown

    Not sure which of those are currently enabled, but I think first steps of providing GitLab compatible Markdown might be:

    1. Check the syntax in the above extensions matches GitLab's.
    2. Create an option for "GitLab Compatible Markdown", with a note that it's still a work in progress.
    3. Add the set of included extensions that most closely matches GitLab MD when this option is selected.

    Further progress may involve finding 3rd party extensions to provide other functionality, or writing our own extensions, but I favour starting with a low risk plan using built in functionality and incrementing from there.

  • 🇺🇸United States ultimike Florida, USA

    @lostcarpark - thanks for looking into this. As we discussed during DrupalEasy office hours, my ideal solution would be (in order of my preference):

    league/commonmark magically introduced a new GitLabFlavoredMarkdownConverter class that I could just drop-in and have it work.
    Some other wonderful open-source minded person or organization created a PHP dependency for GitLab-flavored Markdown that I could include just about as easily as the first option above.

    I don't want to get in the business of partially supporting GitLab-flavored Markdown by enabling Commonmark extensions - if we do that, I feel the chances are currently low that we'll ever be able to claim 100% compatibility with GitLab Markdown.

    -mike

  • 🇩🇪Germany lupe_christoph

    There doesn't seem to be a GitLab flavor extension for CommonMark

    But there is. and has been at least since Jan 13, 2022. The Markdown module supports CommonMark 1.6.7, whose changelog is dated Jan 13, 2022. Markdown also supports PHP Markdown Extra directly and through Parsedown Extra. PHP Markdown Extra has a more extensive list of supported extensions than CommonMark GFM.

    I have at least temporarily given up on Markdown, it blocks the Add text format button with an error. I won't go into details, just so you know my motivation.

    Markdown Easy installs CommonMark 2.5.3, so it gets CommonMark GFM. I've tested the Extensions listed on then GitHub-Flavored Markdown. Autolinks. Disallowed Raw HTML, Strikethrough and Tables work. Tables does not do cell alignment, but that may be my inability to get Limit allowed HTML tags and correct faulty HTML to let the align=foo attribute pass. (Any hints?) The Task List extension partially works, it gobbles the [x] and [ ] up.

    So I believe that unless someone wants to add support for PHP Markdown Extra or Parsedown Extra, this ticket can be closed. But maybe somebody who is familiar with the Markdown Easy and CommonMark code could have a look at the the two defects I found. Tell me if you want me to open tickets for them.

Production build 0.71.5 2024