Specification of math block and math span

[Lemmingh]

Background

Math is a popular extension of Markdown. We have been supporting (rendering) it via markdown-it-katex since version 1.2.0 (2018-04-20).

We now roughly follow pandoc-style. As corner cases arise, however, we need to reconsider the details and get a spec.

Our implementation is not compatible with VS Code's built-in vscode.markdown-math extension in edge cases.

Summary

The conclusion of this thread will be here.

Key references

• Math in Markdown | cben/mathdown Wiki
• Mathematics extension (#457) | CommonMark Discussion
• MathJax extension for LaTeX equations (#698) | CommonMark Discussion
• Ignore LaTeX-like Math mode (or parse it) (#1926) | CommonMark Discussion

[Lemmingh]

Math area

A math area is a math block (leaf block), or math span (inline).

Conventionally, a math block is known as a display math area since it is automatically rendered in display style, and a math span is an inline math area since it is in text style.

Both are necessary.

You would like a dedicated block structure (math block) for the following reasons:

• Expressions are rendered in display style by default.

• You write mathematical expressions (TeX commands) as if you were in their original environment (LaTeX document). You can insert whitespace (including blank lines) as you like.

You would like an inline structure (math span) for the following reasons:

• Expressions are rendered in text style by default.

• You embed mathematical expressions in a paragraph, with restricted use of whitespace.

Big problems

General

• Precedence.

• Exact start condition and end condition.

• Can a math area be empty?

• What if we allow delimiters other than the pandoc-style?

• What if we allow languages other than TeX?

Math block

• Can a math block interrupt other structures?

Math span

• Can a math span be nested inside other structures? Nesting rules?

[Lemmingh]

Sorry to interrupt. But VS Code appears to have an ambitious plan for version 1.58 (microsoft/vscode#124783), which could become a challenge.

At commit 0a57fd87b1d1ef0ff81750f84840ee4303b8800b and 34f0fcaf52a600ba6fc1deb0ef36a1317fda977b, a new built-in extension called "Markdown Math" (vscode.markdown-math) superseded "Markdown Notebook math" (vscode.notebook-markdown-extensions), and contributes a markdown-it plugin to VS Code's built-in Markdown preview. It's powered by a fork of markdown-it-katex (mjbvz/markdown-it-katex) managed by Matt Bierner.

Comparing with the original markdown-it-katex, the fork mainly adds a bunch of inline structures, such as $$ ... $$ and $ ... $. Note that it allows spaces next to a math span delimiter.

I'm scared and not sure why it's happening. Any ideas? @yzhang-gh

[yzhang-gh]

Well, I don't think it is a bad thing as then it (basic math support) will be maintained by VS Code instead of us. But I don't think they would go that further to support \[\], \(\) and care too much about the corner cases we have seen. As you said:

Comparing with the original markdown-it-katex, the fork mainly adds a bunch of inline structures, such as $$ ... $$ and $ ... $. Note that it allows spaces next to a math span delimiter.

I think it is a bug and we can report it to VS Code.

The only downside is now if we would like to set up a spec (of Markdown math) we need to discuss with VS Code, which becomes less convenient.

[Lemmingh]

I don't think they would ... care too much about the corner cases we have seen.

Right. Exactly what I'd like to mean by "challenge" and "scared".

We've classified many cases as error-prone and dangerous. However, VS Code is making an effort to support them, according to commit history.

---

we need to discuss with VS Code

What about inviting Bierner to this thread? Then we might learn why they added that syntax.

[yzhang-gh]

I prefer to collect some specific questions and open an issue in the VS Code repo as there may be more users who would like to discuss.

• Precedence

According to my understanding, a math block is a leaf block, which is similar to a fenced code block (```).
And a math span is an inline element, like inline code `.
So I guess the precedence isn't a problem? We just do the same as ``` and `.

• Exact start condition and end condition.

Do you mean is space allowed before or after $?

• Can a math area be empty?

I guess not, at least for inline math $.

• What if we allow delimiters other than the pandoc-style?

It looks like $ $$ are enough for basic math. Personally I would also like to support \(\) and \[\].

• What if we allow languages other than TeX?

I don't think so. Is there any feature request?

• Can a math block interrupt other structures?
• Can a math span be nested inside other structures? Nesting rules?

To me it is the same question of "precedence". And to avoid unexpected interruption, the question "start/end condition" is important (the pandoc-style seems to be good enough?).

I think we need to raise the No.2~4 questions.