Reference links are lost between dollar signs

[nex3]

This is an issue with the following markdown:

$ [foo][] $

[foo]: http://example.org

Note that $ is not an active character in standard Markdown, although it may be used by extensions. The document above is valid Markdown and [foo][] is interpreted as a link (as in this gist or the CommonMark dingus), but markdownlint produces this error:

MD053/link-image-reference-definitions Link and image reference definitions should be needed [Unused link or image reference definition: "foo"] [Context: "[foo]: http://example.org"]

As a workaround, you can add a \ before the first $.

[DavidAnson]

While wrapping text with dollar signs like you show is not part of the CommonMark specification, it is commonly used in Markdown to provide math/equation support. Commonly enough, in fact, that issues get filed against this project when people expect math behavior and don't get it. Therefore, math syntax is enabled by default for parts of the pipeline. As you note, math syntax does not apply if the leading dollar sign is escaped and that is what I would recommend if you find yourself needing to use the syntax above.

https://github.com/micromark/micromark-extension-math

[nex3]

I think it's highly unexpected behavior to diverge from the specification and the actual behavior of GitHub here. But regardless, it would be valuable to be able to control which non-standard extensions this parser assumed to exist through the configuration file.

[DavidAnson]

I get where you are coming from, but GitHub does actually support math syntax by default. Here is their documentation: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions

So far I have had double digit number of requests to add support for math and a couple of other common-ish extensions whereas this issue may be the first one asking to remove such support. Given how easy it is to escape one's way out of this problem, I am inclined not to make it configurable just yet.

I could do a better job documenting which extensions are enabled, though things are in a bit of flux at the moment while I am busy migrating parsers in the background.

[stof]

Github does not use $ as delimiter but $` and `$

[DavidAnson]

Quoting the GitHub documentation I linked to:

You can either surround the expression with dollar symbols ($), or start the expression with $[backtick] and end it with [backtick]$.

You can also verify this experimentally.

[stof]

When using $ as delimiters, Github still requires the start and end delimiters to be on the same line. They won't consider them delimiters when there is a LF between them, while your linter does. and it also requires that the start delimiter is not followed by spaces (the end delimiter can be preceded by spaces).

[DavidAnson]

Because there is no standard here, implementations may vary. I have generally found the micromark implementation (as used here) to be representative of real-world use and consistent with the specification when available. If you'd like to open a micromark issue for any behaviors you disagree with, I've found that team to be very responsive to input.

For the purpose of this issue, I think the underlying topic is whether it's reasonable for markdownlint to recognize math syntax by default and whether it's necessary to provide a way to opt out of that. I've stated my current position above and remain open to feedback.