Add support for Gitlab Flavoured Markdown math annotation

[bring-shrubbery]

Initial checklist

• [X] I read the support docs
• [X] I read the contributing guide
• [X] I agree to follow the code of conduct
• [X] I searched issues and couldn’t find anything (or linked relevant results below)

Problem

When hosting the documentation written in markdown on Gitlab, the math notation there is written like so: $`x^2 + y^2 = z^2`$ - notice the backticks right after/before the dollar signs, more info here. When running remark-math (which uses this repo for math parsing) the result is a math equation surrounded by backticks.

Solution

It would be nice to be able to have an optional option to treat those backticks as the start/end of the math block (i.e. treat them as part of the dollar sign). This could also be implemented as a "custom math annotation" option, where user could enter their own regex that selects a math block.

Alternatives

This could be implemented as a pre-processing step, but for some tools (like docusaurus in my case), it's hard/clunky to add a pre-processing step to the markdown rendering pipeline.

[wooorm]

Hey

Parsing is done by micromark: https://github.com/micromark/micromark-extension-math. This project deals with ASTs. It’s a bridge between the tokens that micromark emits and mdast.

GitLab math is not a priority to me. There is no math in markdown spec. And the one they use is rather different from some of the others (around backticks but also for in the “block” form). I believe that it is bad for markdown that products dreams up their own markdown extensions and I don’t think it’s manageable for me to reverse-engineer whatever they came up with.

If you want to support GitLab math, and “support” for you here means: a) Remove the backticks (potentially: b) Add support for block math)

Then you can do it at the tree level:

import {visit} from 'unist-util-visit'

/** @type {import('unified').Plugin<Array<void>, import('mdast').Root, import('mdast').Root>} */
export default function remarkMathGitLab() {
  return function (tree) {
    visit(tree, (node, index, parent) => {
      if (node.type === 'inlineMath') {
        node.value = node.value.replace(/^`|`$/g, '')
      }

      if (node.type === 'code' && node.lang === 'math') {
        parent.children[index] = {
          type: 'math',
          value: node.value
        }
      }
    })
  }
}

[bring-shrubbery]

I really hoped I chose the right repo to open the issue on 🤦‍♀️

Interesting, I've hoped that it could become part of the parser, but I do agree that adding features just because some company made up their own syntax is far from the optimal solution.

I did want to keep the backticks in the docs, but just remove them when I deploy Docusaurus to GitLab pages, so manual replace wouldn't work here. I think adding it to the tree parsing is trivial, since syntax here is very deterministic, so I think a simple regex will do for me. I believe we can close this issue then!

Just as a note for people who might need to do a similar thing, this is the replace function regex I used to successfully replace backticks in my project. I've put this into .js file and I'm just running it in CI as an npm script before building the site, so the changes are not committed into the repo itself, and still editable on Gitlab.

.replace(/\$+[^`$]{0,1}\`([^\$]+)\`[^`$]{0,1}\$+/gim, "$$$1$$")

[github-actions[bot]]

Hi! This was closed. Team: If this was fixed, please add phase/solved. Otherwise, please add one of the no/* labels.

[github-actions[bot]]

Hi team! Could you describe why this has been marked as wontfix?

Thanks, — bb

[bring-shrubbery]

@github-actions Common agreement was reached.