starred/markdownlint

Fork 0

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

[GH-ISSUE #733] MD052 and brackets #525

New issue

Closed

opened 2026-03-03 01:27:40 +03:00 by kerem · 2 comments

kerem commented

2026-03-03 01:27:40 +03:00

Owner

Originally created by @FISHMANPET on GitHub (Mar 1, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/733

I've found a couple of issues related to MD052 when there are a lot of brackets.

I made this report using markdownlint-vsoce v0.49.0, which as far as In call uses the latest version (0.27.0) of this library. What initially tipped me off to the problem was seeing errors in my CI/CD pipeline, which is using markdownlint-cli2 v0.6.0 (markdownlint v0.27.0).

Error: Property 'range' of onError parameter is incorrect.

The first would appear to be very similar to #686, but it looks like this case was missed by that fix. I also see #697 that hasn't been released yet, I don't know if that would resolve any of this.

# Broken Link Demo

This Text will [break
This is a broken link [[This] Title[Is][broken]][brokenlink]

[brokenlink]: https://google.com

I came across this in another project and took a look, so I don't know why they have the string [break instead of simply break, but when that line is followed by a line with a link reference where the link title includes brackets, it returns the same error

MD052/reference-links-images: Reference links and images should use a label that is defined [This rule threw an exception: Property 'range' of onError parameter is incorrect.]

I asked the author, and it turns out this was a mistake. I'm not sure if an unmatched bracket like that should be "valid" or not, but it shouldn't cause an exception either way.

In digging through this, I also found that if you add spaces between the bracketed elements in the link title, the error goes away, so this is valid:

# Valid Link Demo

This Text will not [break
This is a not broken link [[This] Title[Is] [broken]][brokenlink]

[brokenlink]: https://google.com

Also when you add a direct link instead of using a reference link, there is no issue, which tells me it's related to the md052 rule specifically

# Valid Link Demo

This Text will not [break
This is a not broken link [[This] Title[Is] [broken]](https://google.com)

Missing label issue when using a reference link where there are touching brackets in the link title

I came across this while poking at the issue above.
This will cause a linting issue (not an exception as above) that I don't think it should.

# Broken Link Demo

This is a broken link [[This] Title[Is][broken]](https://google.com)

It interprets [Is][broken] to be a reference link, and reports that there's no definition for broken

MD052/reference-links-images: Reference links and images should use a label that is defined [Missing link or image reference definition: "broken"]

Putting a space between [Is] and [broken] (This is a broken link [[This] Title[Is] [broken]](https://google.com))

The same issue is present when the link is a reference link:

# Broken Link Demo

This is a broken link [[This] Title[Is][broken]][brokenlink]

[brokenlink]: https://google.com

This reports the same issue as above:

MD052/reference-links-images: Reference links and images should use a label that is defined [Missing link or image reference definition: "broken"]

And once again adding a space between [Is] and [broken] will remove the issue.

This precise case doesn't seem to be covered in the Commonmark Spec, the closest appears to be Example 532 where it says a reference can't exist inside link text, but in this case [broken] is not a reference because there's no [broken] reference. Maybe that rule could be interpreted to say that since references aren't allowed in link text, then nothing that even looks like a reference link should exist in link text. In that case the "broken" cases here would be violating the spec, but maybe a new rule would be appropriate because the reported error isn't actually correct, the violation would be something like "Links may not contain other links" or something like that.

Originally created by @FISHMANPET on GitHub (Mar 1, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/733 I've found a couple of issues related to MD052 when there are a lot of brackets. I made this report using markdownlint-vsoce v0.49.0, which as far as In call uses the latest version (0.27.0) of this library. What initially tipped me off to the problem was seeing errors in my CI/CD pipeline, which is using `markdownlint-cli2 v0.6.0 (markdownlint v0.27.0)`. # Error: Property 'range' of onError parameter is incorrect. The first would appear to be very similar to #686, but it looks like this case was missed by that fix. I also see #697 that hasn't been released yet, I don't know if that would resolve any of this. ``` # Broken Link Demo This Text will [break This is a broken link [[This] Title[Is][broken]][brokenlink] [brokenlink]: https://google.com ``` I came across this in another project and took a look, so I don't know why they have the string `[break` instead of simply `break`, but when that line is followed by a line with a link reference where the link _title_ includes brackets, it returns the same error > MD052/reference-links-images: Reference links and images should use a label that is defined [This rule threw an exception: Property 'range' of onError parameter is incorrect.] I asked the author, and it turns out this was a mistake. I'm not sure if an unmatched bracket like that should be "valid" or not, but it shouldn't cause an exception either way. In digging through this, I also found that if you add spaces between the bracketed elements in the link title, the error goes away, so this is valid: ``` # Valid Link Demo This Text will not [break This is a not broken link [[This] Title[Is] [broken]][brokenlink] [brokenlink]: https://google.com ``` Also when you add a direct link instead of using a reference link, there is no issue, which tells me it's related to the md052 rule specifically ``` # Valid Link Demo This Text will not [break This is a not broken link [[This] Title[Is] [broken]](https://google.com) ``` # Missing label issue when using a reference link where there are touching brackets in the link title I came across this while poking at the issue above. This will cause a linting issue (not an exception as above) that I don't think it should. ``` # Broken Link Demo This is a broken link [[This] Title[Is][broken]](https://google.com) ``` It interprets `[Is][broken]` to be a reference link, and reports that there's no definition for `broken` > MD052/reference-links-images: Reference links and images should use a label that is defined [Missing link or image reference definition: "broken"] Putting a space between `[Is]` and `[broken]` (`This is a broken link [[This] Title[Is] [broken]](https://google.com)`) The same issue is present when the link is a reference link: ``` # Broken Link Demo This is a broken link [[This] Title[Is][broken]][brokenlink] [brokenlink]: https://google.com ``` This reports the same issue as above: > MD052/reference-links-images: Reference links and images should use a label that is defined [Missing link or image reference definition: "broken"] And once again adding a space between `[Is]` and `[broken]` will remove the issue. This precise case doesn't seem to be covered in the Commonmark Spec, the closest appears to be [Example 532](https://spec.commonmark.org/0.30/#example-532) where it says a reference can't exist inside link text, but in this case `[broken]` is not a reference because there's no `[broken]` reference. Maybe that rule could be interpreted to say that since references aren't allowed in link text, then nothing that even _looks_ like a reference link should exist in link text. In that case the "broken" cases here would be violating the spec, but maybe a new rule would be appropriate because the reported error isn't actually correct, the violation would be something like "Links may not contain other links" or something like that.

kerem

2026-03-03 01:27:40 +03:00

closed this issue
added the
bug

fixed in next
labels

kerem commented

2026-03-03 01:27:41 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 1, 2023):

The fix for 697 should bring the handling of nested brackets fully into compliance with the specification. I will try to go through all of your examples using the latest implementation in "next" branch in a few days. The specification says the innermost link takes precedence when valid; that slightly complicates matters for this rule, which tries to highlight links that are supposed to be valid, but aren't (potentially due to a mistake).

@DavidAnson commented on GitHub (Mar 1, 2023): The fix for 697 should bring the handling of nested brackets fully into compliance with the specification. I will try to go through all of your examples using the latest implementation in "next" branch in a few days. The specification says the innermost link takes precedence when valid; that slightly complicates matters for this rule, which tries to highlight links that are supposed to be valid, but aren't (potentially due to a mistake).

kerem commented

2026-03-03 01:27:41 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 6, 2023):

Behavior and analysis of your examples in next branch:

# Broken Link Demo

This Text will [break
This is a broken link [[This] Title[Is][broken]][brokenlink]

[brokenlink]: https://google.com

4 - MD052 / reference-links-images Reference links and images should use a label that is defined [Missing link or image reference definition: "broken"] [Context: "[Is][broken]"]

This is correct because if [broken] did exist, then the inner link would bind to it and the rule is reporting that link is possibly broken (even though the outer link is not). Your subsequent two examples that add a space to break the inner link continue to report no violations as expected.

# Broken Link Demo

This is a broken link [[This] Title[Is][broken]](https://google.com)

3 - MD034 / no-bare-urls Bare URL used [Context: "https://google.com"] [Fix]
3 - MD052 / reference-links-images Reference links and images should use a label that is defined [Missing link or image reference definition: "broken"] [Context: "[Is][broken]"]

This is correct for the same reason as above.

# Broken Link Demo

This is a broken link [[This] Title[Is][broken]][brokenlink]

[brokenlink]: https://google.com

3 - MD052 / reference-links-images Reference links and images should use a label that is defined [Missing link or image reference definition: "broken"] [Context: "[Is][broken]"]

Ditto, though there is no longer a bare URL.

If we agree (and I think we do) that [Is][broken] on its own should produce a violation due to this appearing to be a reference link and [broken] not being defined, the above behavior when this same construct is nested within another link follows. The relevant section of the specification is https://spec.commonmark.org/0.30/#links which states “Links may not contain other links, at any level of nesting. If multiple otherwise valid link definitions appear nested inside each other, the inner-most definition is used.”.

@DavidAnson commented on GitHub (Mar 6, 2023): Behavior and analysis of your examples in `next` branch: *** ```md # Broken Link Demo This Text will [break This is a broken link [[This] Title[Is][broken]][brokenlink] [brokenlink]: https://google.com ``` _4_ - [MD052 / reference-links-images](https://github.com/DavidAnson/markdownlint/blob/v0.27.0/doc/md052.md) Reference links and images should use a label that is defined [_Missing link or image reference definition: "broken"_] [_Context: "[Is][broken]"_] This is correct because if `[broken]` did exist, then the inner link would bind to it and the rule is reporting that link is possibly broken (even though the outer link is not). Your subsequent two examples that add a space to break the inner link continue to report no violations as expected. *** ```md # Broken Link Demo This is a broken link [[This] Title[Is][broken]](https://google.com) ``` _3_ - [MD034 / no-bare-urls](https://github.com/DavidAnson/markdownlint/blob/v0.27.0/doc/md034.md) Bare URL used [_Context: "https://google.com"_] [_Fix_] _3_ - [MD052 / reference-links-images](https://github.com/DavidAnson/markdownlint/blob/v0.27.0/doc/md052.md) Reference links and images should use a label that is defined [_Missing link or image reference definition: "broken"_] [_Context: "[Is][broken]"_] This is correct for the same reason as above. *** ```md # Broken Link Demo This is a broken link [[This] Title[Is][broken]][brokenlink] [brokenlink]: https://google.com ``` _3_ - [MD052 / reference-links-images](https://github.com/DavidAnson/markdownlint/blob/v0.27.0/doc/md052.md) Reference links and images should use a label that is defined [_Missing link or image reference definition: "broken"_] [_Context: "[Is][broken]"_] Ditto, though there is no longer a bare URL. *** If we agree (and I think we do) that `[Is][broken]` on its own should produce a violation due to this appearing to be a reference link and `[broken]` not being defined, the above behavior when this same construct is nested within another link follows. The relevant section of the specification is <https://spec.commonmark.org/0.30/#links> which states “Links may not contain other links, at any level of nesting. If multiple otherwise valid link definitions appear nested inside each other, the inner-most definition is used.”.

kerem referenced this issue

2026-03-07 20:06:13 +03:00

[GH-ISSUE #525] MD011: should not be triggered by content of inline code span #2275