Skip to content

[markdown] Implement `$` and `$$` for math fencing in math filter

What does this MR do and why?

Add the $...$ and $$...$$ syntax for inline and display math in markdown documents.

We're following the Pandoc syntax from https://pandoc.org/MANUAL.html#extension-tex_math_dollars:

Anything between two $ characters will be treated as TeX math. The opening $ must have a non-space character immediately to its right, while the closing $ must have a non-space character immediately to its left, and must not be followed immediately by a digit. Thus, $20,000 and $30,000 won’t parse as math. If for some reason you need to enclose text in literal $ characters, backslash-escape them and they won’t be treated as math delimiters.

For display math, use $$ delimiters. (In this case, the delimiters may be separated from the formula by whitespace. However, there can be no blank lines between the opening and closing $$ delimiters.)

Backslash-escaped $ does not work in this MR. See https://gitlab.com/gitlab-org/gitlab/-/work_items/113462870

Screenshots or screen recordings

Screenshots are required for UI changes, and strongly recommended for all other merge requests.

How to set up and validate locally

Enable the feature flag markdown_dollar_math for a group

group = Group.find_by_full_path('flightjs')
Feature.enable(:markdown_dollar_math, group)

Test Data, will render correctly only when MR is deployed

inline math using $...$ syntax

  • $2+2$ : 2+2
  • $22+1$ and $2390985 + a^2$ : 22+1 and 2390985 + a^2
  • $2390985 and $2+2$ : $2390985 and 2+2
  • and $2+2$ : and 2+2
  • $2+2$ $2390985 and gitlab-org/gitlab$2390985 $2+2$ : 2+2 $2390985 and $2390985 2+2

inline math using $`...`$ syntax

  • $`2+2`$ : 2+2
  • $`22+1`$ and $`22 + a^2`$ : 22+1 and 22 + a^2
  • $2390985 and $`2+2`$ : $2390985 and 2+2
  • and $`2+2`$ : and 2+2
  • $`2+2`$ $2390985 and gitlab-org/gitlab$2390985 $`2+2`$ : 2+2 $2390985 and $2390985 2+2
  • test $$`2+2`$$ test : test $2+2$ test

display math using ```math...``` syntax

  • Block math using ```math...```

    a^2 + b^2 = c^2

inline display math using $$...$$ syntax

  • $$2+2$$ : 2+2
  • $$22+1$$ and $$22 + a^2$$ : 22+1 and 22 + a^2
  • $2390985 and $$2+2$$ : $2390985 and 2+2
  • $$2+2$$ $2390985 and gitlab-org/gitlab$2390985 $$2+2$$ : 2+2 $2390985 and $2390985 2+2
  • gitlab-org/gitlab$2390985 and $$a^2 + b^2 = c^2$$ : $2390985 and a^2 + b^2 = c^2

block display math using $$\n...\n$$ syntax

  • $$\n2+2\n$$ :

    $$ 2+2 $$

properly ignored syntax

  • $20,000 and $30,000 : $20,000 and $30,000

  • and $2+\$2$ : and 2+\$2

  • `2+2` : 2+2

  • test $`2+2` test : test $2+2 test

  • test `2+2`$ test : test 2+2$ test

  • _$_`2+2`_$_ : $_2+2_$

  • test $$\n2+2\n$$

    test $$ 2+2 $$

Not working

  • using a literal dollar sign \$ in the math doesn't work
    • $2+2$ $2390985 and gitlab-org/gitlab$2390985 $2+2\$$ : 2+2 $2390985 and $2390985 2+2\$
    • $\$2+\$2$ $2390985 and $1 $2+2\$$ : \$2+\$2 $2390985 and $1 2+2\$

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Related to #21757 (closed) and https://gitlab.com/gitlab-org/gitlab/-/work_items/113462870

Edited by Brett Walker

Merge request reports