Set up Markdownlint to recognize math expressions

[SichangHe]

I just went through the tedious process to set up markdownlint to recognize $$…$$ and $…$ in my markdown. See the commit in my .config repo for details.

Motivation

Previously, by default and my configuration, markdownlint on null-ls gives an error on anything like this saying that the emphasis should be *

$$
\frac{∂f}{∂x_n}\Bigr|_{x_1=a_1,\cdots,x_n=a_n,\cdots}
=f_{x_n}(a_1,a_2,\cdots)
=g'(a_n)
$$

However, this problem does not show up in the VSCode plugin. The reason is that they use a math plugin for markdownlint.

Steps

Switch to markdownlint-cli2 so we can add the plugin. For me, I installed it with Homebrew because Mason does not have it.

Set the markdownlint-cli2 argument to $FILENAME so it works.

Make a .markdownlint-cli2.jsonc like this:

{
    "config": {
        // …
    },
    "markdownItPlugins": [
        [
            "@iktakahiro/markdown-it-katex"
        ]
    ]
}

markdownlint-cli2 does not respect global config 😢, so we need to use markdownlint-cli2-config and put make the config file its first argument.

It does not run because @iktakahiro/markdown-it-katex does not exist, npm install -g.

macOS cannot find global NPM packages, so I need to set $NODE_PATH.

Finally, then, it would work as expected. The config looks like this:

local null_ls = require('null-ls')
null_ls.setup {
    sources = {
        null_ls.builtins.diagnostics.markdownlint_cli2.with {
            command = 'markdownlint-cli2-config',
            args = {
                U.fn.expand('~/.config/.markdownlint-cli2.jsonc'),
                '$FILENAME'
            },
        },
    },
}

Pities

• This is not portable. If I move to another machine, I would need to do the node stuff again.
• There exists no formatting option for markdownlint-cli2. And, I do not know a way to call markdownlint-cli2-fix with the config file.

[SichangHe]

Moving to markdown-it-texmath for the markdownItPlugins because the VSCode extension seems to have moved to it. It requires katex from NPM as well.

[jose-elias-alvarez]

I don't think there's anything we can do about the lack of portability - maybe Mason can provide some sort of solution?

As for the second issue, I went over the documentation and it doesn't seem that this is supported. I have no idea why they chose to set up the CLI like this instead of just merging command line options with a config file. It may be worth opening an issue upstream.

[SichangHe]

I have commented in this issue.

[SichangHe]

In markdownlint-cli2 v0.7.0, the issue that markdownlint-cli2-config does not respect "fix": true is fixed.
So, I could get a work around for formatting:

null_ls.builtins.formatting.markdownlint.with {               
    command = 'markdownlint-cli2-config',                     
    args = {                                                  
        U.fn.expand('~/.config/fix.markdownlint-cli2.jsonc'), 
        '$FILENAME'                                           
    },                                                        
},                                                            

Here, fix.markdownlint-cli2.jsonc is a duplication of .markdownlint-cli2.jsonc with "fix": true.

Reference for future people:
SichangHe/.config@bde3307