[GH-ISSUE #1893] Unexpected trigger of MD051 #2618

New issue

Closed

opened 2026-03-07 20:09:25 +03:00 by kerem · 3 comments

kerem commented

2026-03-07 20:09:25 +03:00

Owner

Originally created by @davidorme on GitHub (Dec 16, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1893

We're running markdownlint as part of a pre-commit flow using markdownlint-cli.

With the most recent update, it caught a number of new line length issues (MD013) but in fixing the repo to remove those problems, we're now seeing what seem to be spurious MD051 errors ("Link fragments should be valid"). I've pushed the offending lines onto our repo origin. The offending lines in their original file are here:

github.com/ImperialCollegeLondon/virtual_ecosystem@9b880b1335/docs/source/virtual_ecosystem/theory/microclimate_theory.md (L28-L40)

And the resulting GA pre-commit output is here and mirrors what I see locally:

https://github.com/ImperialCollegeLondon/virtual_ecosystem/actions/runs/20268159638/job/58196586322?pr=1222

As far as I can tell, those links should be fine:

The links are all to headings that occur in the document. For example the first issue:

docs/source/virtual_ecosystem/theory/microclimate_theory.md:31:8 
error MD051/link-fragments Link fragments should be valid 
[Context: "[state variables](#key-microclimatic-state-variables)"]

seems like it should match this heading:

## Key microclimatic state variables

VSCode can successfully follow the link to the correct section

Originally created by @davidorme on GitHub (Dec 16, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1893 We're running `markdownlint` as part of a pre-commit flow using `markdownlint-cli`. With the most recent update, it caught a number of new line length issues (MD013) but in fixing the repo to remove those problems, we're now seeing what seem to be spurious MD051 errors ("Link fragments should be valid"). I've pushed the offending lines onto our repo `origin`. The offending lines in their original file are here: https://github.com/ImperialCollegeLondon/virtual_ecosystem/blob/9b880b13353f4e6daf9794a3413b78bcd422434f/docs/source/virtual_ecosystem/theory/microclimate_theory.md?plain=1#L28-L40 And the resulting GA pre-commit output is here and mirrors what I see locally: https://github.com/ImperialCollegeLondon/virtual_ecosystem/actions/runs/20268159638/job/58196586322?pr=1222 As far as I can tell, those links should be fine: * The links are all to headings that occur in the document. For example the first issue: ```sh docs/source/virtual_ecosystem/theory/microclimate_theory.md:31:8 error MD051/link-fragments Link fragments should be valid [Context: "[state variables](#key-microclimatic-state-variables)"] ``` seems like it should match [this heading](https://github.com/ImperialCollegeLondon/virtual_ecosystem/blob/9b880b13353f4e6daf9794a3413b78bcd422434f/docs/source/virtual_ecosystem/theory/microclimate_theory.md?plain=1#L158): ```md ## Key microclimatic state variables ``` * VSCode can successfully follow the link to the correct section

kerem

2026-03-07 20:09:25 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:09:26 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 17, 2025):

From what I can tell on my phone, the issue is your changes to lines 123–125 reformatting the multi-line math expression there. Instead of being a block expression, it seems to be changed to an inline and I think the parser is never exiting it. Therefore, the following Markdown text in the file is not recognized as headings, etc.. Reverting just your changes to that section resolves the bogus violations from what I can tell. It's a little confusing because GitHub handles it fine, but I think the micromark math extension has slightly different logic.

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

@DavidAnson commented on GitHub (Dec 17, 2025): From what I can tell on my phone, the issue is your changes to lines 123–125 reformatting the multi-line math expression there. Instead of being a block expression, it seems to be changed to an inline and I think the parser is never exiting it. Therefore, the following Markdown text in the file is not recognized as headings, etc.. Reverting just your changes to that section resolves the bogus violations from what I can tell. It's a little confusing because GitHub handles it fine, but I think the micromark math extension has slightly different logic. https://github.com/micromark/micromark-extension-math

kerem commented

2026-03-07 20:09:26 +03:00

Author

Owner

@davidorme commented on GitHub (Dec 17, 2025):

That's exactly it. I hadn't spotted that mangling of the equation block, or that it was the links in the bottom half of the document that were flagged as broken. Should have spotted it - many thanks.

@davidorme commented on GitHub (Dec 17, 2025): That's exactly it. I hadn't spotted that mangling of the equation block, or that it was the links in the bottom half of the document that were flagged as broken. Should have spotted it - many thanks.

kerem commented

2026-03-07 20:09:26 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 17, 2025):

Normally with something like this, I can just point to the rendered output and it's obvious something went wrong in the middle. Not so this time. Sorry about the trouble!

@DavidAnson commented on GitHub (Dec 17, 2025): Normally with something like this, I can just point to the rendered output and it's obvious something went wrong in the middle. Not so this time. Sorry about the trouble!