[GH-ISSUE #1118] Question: New MD051 warnings upgrading from v14 to v15 #2463

New issue

Closed

opened 2026-03-07 20:07:59 +03:00 by kerem · 4 comments

kerem commented

2026-03-07 20:07:59 +03:00

Owner

Originally created by @CodeBlanch on GitHub (Feb 1, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1118

Hey @DavidAnson!

When we bump from v14 to v15 we are getting new MD051 warnings: https://github.com/open-telemetry/opentelemetry-dotnet/actions/runs/7716090575/job/21032134820?pr=5290#step:3:13

The fragments seem fine from what I can gather. Is this expected?

/cc @alanwest

Originally created by @CodeBlanch on GitHub (Feb 1, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1118 Hey @DavidAnson! When we bump from v14 to v15 we are getting new MD051 warnings: https://github.com/open-telemetry/opentelemetry-dotnet/actions/runs/7716090575/job/21032134820?pr=5290#step:3:13 The fragments seem fine from what I can gather. Is this expected? /cc @alanwest

kerem

2026-03-07 20:07:59 +03:00

closed this issue
added the
question
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Feb 1, 2024):

Sorry, I can't tell why this rule is complaining from my phone, but my guess is the inline code span is interfering. I'll try to have a look soon. You may want to disable that rule for that file temporarily if it's blocking PRs.

@DavidAnson commented on GitHub (Feb 1, 2024): Sorry, I can't tell why this rule is complaining from my phone, but my guess is the inline code span is interfering. I'll try to have a look soon. You may want to disable that rule for that file temporarily if it's blocking PRs.

kerem commented

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

Author

Owner

@CodeBlanch commented on GitHub (Feb 1, 2024):

@DavidAnson Just FYI we worked around the issue by tweaking the markdown here: https://github.com/open-telemetry/opentelemetry-dotnet/pull/5306

@CodeBlanch commented on GitHub (Feb 1, 2024): @DavidAnson Just FYI we worked around the issue by tweaking the markdown here: https://github.com/open-telemetry/opentelemetry-dotnet/pull/5306

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Feb 2, 2024):

Great, thanks for letting me know! I swear those backticks were in the file I looked at, so I may have picked the wrong file on my phone due to the small screen and seemingly many similar file names. Based on the file I saw, I think you wanted those backticks you just added anyway, so maybe this is a blessing in disguise. :) I will go on and have a look at why this happened, though.

@DavidAnson commented on GitHub (Feb 2, 2024): Great, thanks for letting me know! I swear those backticks were in the file I looked at, so I may have picked the wrong file on my phone due to the small screen and seemingly many similar file names. Based on the file I saw, I think you wanted those backticks you just added anyway, so maybe this is a blessing in disguise. :) I will go on and have a look at why this happened, though.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Feb 2, 2024):

Okay, this isn't a bug in markdownlint.

Here's one of the "before" headings from your change: https://dlaa.me/markdownlint/#%25m%23%20Issue%201118%0A%0A%23%23%20ConventionalRouting%3A%20Area%20using%20area%3Aexists%2C%20default%20controller%2Faction%0A

Note that it renders weird - that's because :exists is treated as an inline Markdown directive which is newly supported in the latest release of markdownlint. You can read more here: https://github.com/micromark/micromark-extension-directive

Directives are for extending, so the tool doesn't know if a particular one is valid or not. If the parser sees valid directive syntax, it treats it as a directive. Which means the heading above doesn't say what it looks like it says and there's a mis-match so MD051 rightly triggers.

Now, I would have assumed a directive needed to be preceded by a space character, but I don't see that called out in the "spec": https://talk.commonmark.org/t/generic-directives-plugins-syntax/444

If you want to read that whole discussion, be my guest. If you find there's supposed to be a space, we can log that as an issue against the micromark code. But I don't see this as an open/closed issue there, so I suspect it is deliberate.

Your change to put the relevant text in an inline code span avoids the issue by taking the colon/text out of the normal flow.

Unless you feel otherwise, I will close this as "by design". Thanks for reporting it!

@DavidAnson commented on GitHub (Feb 2, 2024): Okay, this isn't a bug in `markdownlint`. Here's one of the "before" headings from your change: https://dlaa.me/markdownlint/#%25m%23%20Issue%201118%0A%0A%23%23%20ConventionalRouting%3A%20Area%20using%20area%3Aexists%2C%20default%20controller%2Faction%0A Note that it renders weird - that's because `:exists` is treated as an inline Markdown directive which is newly supported in the latest release of `markdownlint`. You can read more here: https://github.com/micromark/micromark-extension-directive Directives are for extending, so the tool doesn't know if a particular one is valid or not. If the parser sees valid directive syntax, it treats it as a directive. Which means the heading above doesn't say what it looks like it says and there's a mis-match so MD051 rightly triggers. Now, I would have assumed a directive needed to be preceded by a space character, but I don't see that called out in the "spec": https://talk.commonmark.org/t/generic-directives-plugins-syntax/444 If you want to read that whole discussion, be my guest. If you find there's supposed to be a space, we can log that as an issue against the `micromark` code. But I don't see this as an open/closed issue there, so I suspect it is deliberate. Your change to put the relevant text in an inline code span avoids the issue by taking the colon/text out of the normal flow. Unless you feel otherwise, I will close this as "by design". Thanks for reporting it!