Change Request: Support Math

[lumirlumir]

Environment

ESLint version: v9.23.0
@eslint/markdown version: v6.3.0
Node version: v20.18.0
npm version: v10.9.2
Operating System: Windows 11

What problem do you want to solve?

Hello,

Math equation expressions using LaTeX are widely used in Markdown and are compatible with both CommonMark and GFM.

Additionally, with micromark-extension-math and mdast-util-math available, integrating them into @eslint/markdown should be straightforward, just like we did in #328.

Therefore, I’d like to propose adding support for Math syntax in @eslint/markdown.

What do you think is the correct solution?

Let's use micromark-extension-math and mdast-util-math.

We can add an option to languageOptions.math as shown below, allowing it to be set to either true or false.

// eslint.config.js
import markdown from "@eslint/markdown";

export default [
    {
        files: ["**/*.md"],
        plugins: {
            markdown
        },
        language: "markdown/gfm",
        languageOptions: {
            frontmatter: true,
            math: true // It can be `true` or `false`.
        },
        rules: {
            "markdown/no-html": "error"
        }
    }
];

Participation

• I am willing to submit a pull request for this change.

Additional comments

No response

[nzakas]

I'm not opposed, I just don't want to get into the habit of adding in every micromark extension just because it exists. In this case, I'm not sure that adding support for math actually adds to linting experience in any way. I doubt people will be writing rules to lint the mathematical formulas in the document.

We can leave this open to see if there's any further interest or use cases in the community. At this point, I'm not inclined to add this.

[nzakas]

Closing for now as I don't think there's a lot of demand for this. We can always revisit in the future if that changes.

[lumirlumir]

As @eslint/markdown grows and more error-prone syntax-detection rules are added, I've encountered some false positives while working on math equations in Markdown documents. So, I am kindly re-opening this issue.

While working on math equations (specifically, when I'm writing solutions for algorithm problem solving, e.g., on Codeforces), I've encountered the following kinds of false positives related to the @eslint/markdown rules.

For example:

When writing permutation:

It leads to a false positive for the markdown/no-missing-label-refs rule.

• Code

  $[1, 2, 3, 4]$

• Rendered

  $[1, 2, 3, 4]$

---

When writing matrix-vector multiplication:

It leads to false positives for the markdown/no-missing-label-refs and markdown/no-reversed-media-syntax rules.

• Code

  $(A \cdot x)[i] = \sum_{j=1}^{n} A[i][j] , x[j]$

• Rendered

  $(A \cdot x)[i] = \sum_{j=1}^{n} A[i][j] , x[j]$

---

When writing convolution:

It leads to a false positive for the markdown/no-space-in-emphasis rule.

• Code

  $(f * g)(x) + (h * k)(x)$

• Rendered

  $(f * g)(x) + (h * k)(x)$

---

---

For the reasons above, I'd like to ask would it be okay to add a math option to @eslint/markdown.

[nzakas]

I'm still not sure it's worth adding this for everyone because, so far, you're the only one who has requested this change.

I'm wondering if it might be better to allow passing in a custom parser that people can modify however they want.

@eslint/eslint-team thoughts?

(Just a note: When you reopen an issue be sure to move it on the Triage board).

[lumirlumir]

I realize I didn't provide enough rationale for this feature request.

Personally, I believe math equations are a non-standard but useful and widely adopted feature—much like Front Matter, though less standardized.

Here are some reasons:

The Math option aligns with markdownlint's behavior

markdownlint doesn't report errors for math equations.

I demonstrated this with the third example under "When writing convolution:" and it produced no errors for the math. This is because markdownlint — particularly the vscode-markdownlint extension — can natively recognize math equations:

• Related Code: https://github.com/DavidAnson/vscode-markdownlint/blob/a05bf6e578aee90347fcde4bc6ea44dadd48ebe5/extension.js#L365
• Related Issue: MD037 triggers when using inline LaTeX DavidAnson/markdownlint#391 (comment)

This makes migrating rules from markdownlint to @eslint/markdown — including for me — more difficult. (Currently, the only way to ignore the error is to manually insert <!-- eslint-disable --> comments.)

There is demand for LaTeX (Math) syntax in the mature Markdown linter ecosystem

Looking at the mature Markdown linter ecosystem like markdownlint, there is demand for LaTeX syntax which is related with false positives:

• markdownlint Issue: https://github.com/DavidAnson/markdownlint/issues?q=is%3Aissue%20state%3Aclosed%20latex

remark-lint can accept a custom parser:

it might be better to allow passing in a custom parser

Yes, that could be another option, since remark-lint allows passing a custom parser:

https://github.com/remarkjs/remark-lint?tab=readme-ov-file#syntax

GitHub natively supports LaTeX (math equations) in Markdown

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions

GitHub's Markdown natively supports LaTeX.

I believe this aligns with the RFC we're reviewing about GitHub Alerts syntax (eslint/rfcs#138 (comment)).

Since we're adding the alert option because GitHub recognizes Alerts syntax as a valid syntax, I think math should be handled the same way, as it's already supported natively by GitHub Markdown.

---

I hope the first option is simply passing a math option to the parser; I’d still welcome the custom-parser approach if that’s preferred.

[nzakas]

@eslint/eslint-team I could use some more opinions on this.