starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 09:16:02 +03:00

[GH-ISSUE #1262] Reference links are lost between dollar signs #2497

New issue

Closed

opened 2026-03-07 20:08:19 +03:00 by kerem · 7 comments

kerem commented

2026-03-07 20:08:19 +03:00

Owner

Originally created by @nex3 on GitHub (Jun 17, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1262

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 $.

Originally created by @nex3 on GitHub (Jun 17, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1262 This is an issue with the following markdown: ```md $ [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](https://gist.github.com/nex3/be3608a7d27b39f562e70f7d05d1695e) or [the CommonMark dingus](https://spec.commonmark.org/dingus/?text=%24%20%5Bfoo%5D%5B%5D%20%24%0A%0A%5Bfoo%5D%3A%20http%3A%2F%2Fexample.org%0A)), 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 `$`.

kerem

2026-03-07 20:08:19 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:08:21 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 18, 2024):

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

@DavidAnson commented on GitHub (Jun 18, 2024): 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

kerem commented

2026-03-07 20:08:21 +03:00

Author

Owner

@nex3 commented on GitHub (Jun 18, 2024):

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.

@nex3 commented on GitHub (Jun 18, 2024): 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.

kerem commented

2026-03-07 20:08:21 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 19, 2024):

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.

@DavidAnson commented on GitHub (Jun 19, 2024): 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.

kerem commented

2026-03-07 20:08:21 +03:00

Author

Owner

@stof commented on GitHub (Jun 19, 2024):

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

@stof commented on GitHub (Jun 19, 2024): Github does not use `$` as delimiter but <code>$\`</code> and <code>\`$</code>

kerem commented

2026-03-07 20:08:21 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 19, 2024):

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.

@DavidAnson commented on GitHub (Jun 19, 2024): 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.

kerem commented

2026-03-07 20:08:21 +03:00

Author

Owner

@stof commented on GitHub (Jun 19, 2024):

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).

@stof commented on GitHub (Jun 19, 2024): 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).

kerem commented

2026-03-07 20:08:21 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 19, 2024):

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.

@DavidAnson commented on GitHub (Jun 19, 2024): 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.