[markdown] Use `$...$` and `$$...$$` for math fencing in Markdown documents
Description
Currently the existing math syntax supported by GitLab uses the syntax $`...`$
for inline math, and ```math...```
for display math.
Although not a standard, the "dollar math" syntax, $...$
and $$...$$
, has become a commonly accepted syntax, including pandoc, MultiMarkdown, and GitHub
The original proposal suggests using a ${...}$
and $${...}$$
syntax. This is a novel and unique idea since "such fencing will render correctly in native LaTeX too as the curly-braces are treated as grouping and ignored"
However, doing so would still put GitLab using its own unique syntax, and limit markdown interoperability with other tools.
As such, we will add the $...$
and $$...$$
syntax. In order to make parsing and syntax less ambiguous, we will adhere to the heuristics specified by pandoc
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.)
The current GitLab math syntax will continue to exist. $`...`$
should be considered deprecated, while ```math...```
will still be considered a primary method for display math.
Update: now that GFM and Pandoc support our original math syntax, there is no reason to deprecate it. We will continue to enhance/fix our dollar math support.
Original proposal
Just had a thought about Markdown math fencing...
Similar issue to gitlab-ce#29086:-
GitLab currently uses $`e^x`$
for inline math and fenced code block with language id math
for block math:
```math
\int e^t dt
```
Neither of these syntaxes is supported by external Markdown editors or the original LaTeX language by default. This means that these documents only display correctly on GitLab.
I am thankful that GitLab thought about how to support mathematics in markdown on site, and I believe that much effort went into the deliberation. This is a tough issue because converting pure $
pair into LaTeX will result in much false positive, yet (
, [
& {
type of parenthesis were already heavily used in usual text fencing. We will most likely need 2-characters at least to do proper fencing that does not result in false positive. \(
, \[
, and \\(
etc were proposed but they 1.) do have false positive, e.g. with regex, and 2.) are not supported by the original LaTeX specification.
Proposal
Fence inline math with ${
and }$
pair for inline math, and fence block math with $${
and }$$
. For example ${\alpha}$
will render in LaTeX. Notice that such fencing will render correctly in native LaTeX too as the curly-braces are treated as grouping and ignored.
I believe with a quick search through GitLab & GitHub repos that there isn't much documents with these symbols. It will be good to quickly reserve them for Markdown math usage so that the world can start typing math with code =)