starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 01:05:55 +03:00

[GH-ISSUE #273] MD034 - Bare URL used --> false positive for Reference Links with comment block #232

New issue

Closed

opened 2026-03-03 01:24:56 +03:00 by kerem · 5 comments

kerem commented

2026-03-03 01:24:56 +03:00

Owner

Originally created by @N7K4 on GitHub (Apr 15, 2020).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/273

On my Jekyll blog, I use often link references to group the long URLs at the end of the post. I start the block with {% comment %}{% endcomment %}

Works no MD034:

[MD034][ref001]

[ref001]: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines
[ref002]: https://github.com
[ref003]: https://github.com/DavidAnson

False positive of MD034, I got the warning because of my comment line:

[MD034][ref001]

{% comment %}<!-- Link References -->{% endcomment %}
[ref001]: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines
[ref002]: https://github.com
[ref003]: https://github.com/DavidAnson

Workaround of MD034, add a empty line between comment and list of references:

[MD034][ref001]

{% comment %}<!-- Link References -->{% endcomment %}

[ref001]: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines
[ref002]: https://github.com
[ref003]: https://github.com/DavidAnson

Is there a way to get ride of the MD034 warning, without the empty line?

Originally created by @N7K4 on GitHub (Apr 15, 2020). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/273 On my Jekyll blog, I use often link references to group the long URLs at the end of the post. I start the block with `{% comment %}{% endcomment %}` Works no MD034: ``` [MD034][ref001] [ref001]: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines [ref002]: https://github.com [ref003]: https://github.com/DavidAnson ``` **False positive** of MD034, I got the warning because of my comment line: ``` [MD034][ref001] {% comment %}{% endcomment %} [ref001]: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines [ref002]: https://github.com [ref003]: https://github.com/DavidAnson ``` **Workaround** of MD034, add a empty line between comment and list of references: ``` [MD034][ref001] {% comment %}{% endcomment %} [ref001]: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines [ref002]: https://github.com [ref003]: https://github.com/DavidAnson ``` Is there a way to get ride of the MD034 warning, without the empty line?

kerem

2026-03-03 01:24:56 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:24:57 +03:00

Author

Owner

@DavidAnson commented on GitHub (Apr 15, 2020):

I’ll look into why that blank line makes a difference here, but in the meantime you might just add a comment to disable this rule near the end of your file above that comment block.

For example:

<!-- markdownlint-disable MD034 -->

@DavidAnson commented on GitHub (Apr 15, 2020): I’ll look into why that blank line makes a difference here, but in the meantime you might just add a comment to disable this rule near the end of your file above that comment block. For example: ```  ```

kerem commented

2026-03-03 01:24:57 +03:00

Author

Owner

@DavidAnson commented on GitHub (Apr 25, 2020):

The behavior you report above is correct. The way the problematic structure looks to the parser is that the bottom block is one large paragraph since the parser does not understand the (unsupported) comment line. Because of that, the link references aren’t interpreted as you intend which means they look like text which means the URLs within look like bare URLs.

Your workaround of adding a blank link works because it separates the comment text from the link references and allows them to be recognized for what they are.

Here’s a link to see how the parser interprets this:
https://markdown-it.github.io/#md3=%7B%22source%22%3A%22%23%20Issue%20273%5Cn%5Cn%5BMD034%5D%5Bref001%5D%5Cn%5Cn%7B%25%20comment%20%25%7D%3C!--%20Link%20References%20--%3E%7B%25%20endcomment%20%25%7D%5Cn%5Bref001%5D%3A%20%28https%3A%2F%2Fgithub.com%2FDavidAnson%2Fmarkdownlint%2Fblob%2Fmaster%2Fdoc%2FRules.md%23md031---fenced-code-blocks-should-be-surrounded-by-blank-lines%29%5Cn%5Bref002%5D%3A%20%28https%3A%2F%2Fgithub.com%29%5Cn%5Bref003%5D%3A%20%28https%3A%2F%2Fgithub.com%2FDavidAnson%29%5Cn%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22html%22%7D%7D

@DavidAnson commented on GitHub (Apr 25, 2020): The behavior you report above is correct. The way the problematic structure looks to the parser is that the bottom block is one large paragraph since the parser does not understand the (unsupported) comment line. Because of that, the link references aren’t interpreted as you intend which means they look like text which means the URLs within look like bare URLs. Your workaround of adding a blank link works because it separates the comment text from the link references and allows them to be recognized for what they are. Here’s a link to see how the parser interprets this: https://markdown-it.github.io/#md3=%7B%22source%22%3A%22%23%20Issue%20273%5Cn%5Cn%5BMD034%5D%5Bref001%5D%5Cn%5Cn%7B%25%20comment%20%25%7D%3C!--%20Link%20References%20--%3E%7B%25%20endcomment%20%25%7D%5Cn%5Bref001%5D%3A%20%28https%3A%2F%2Fgithub.com%2FDavidAnson%2Fmarkdownlint%2Fblob%2Fmaster%2Fdoc%2FRules.md%23md031---fenced-code-blocks-should-be-surrounded-by-blank-lines%29%5Cn%5Bref002%5D%3A%20%28https%3A%2F%2Fgithub.com%29%5Cn%5Bref003%5D%3A%20%28https%3A%2F%2Fgithub.com%2FDavidAnson%29%5Cn%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22html%22%7D%7D

kerem commented

2026-03-03 01:24:57 +03:00

Author

Owner

@nschonni commented on GitHub (Apr 26, 2020):

The braces around the links aren't valid for reference links https://spec.commonmark.org/0.29/#reference-link. They should just be the value inside the braces if it wasn't a reference link

@nschonni commented on GitHub (Apr 26, 2020): The braces around the links aren't valid for reference links https://spec.commonmark.org/0.29/#reference-link. They should just be the value inside the braces if it wasn't a reference link

kerem commented

2026-03-03 01:24:58 +03:00

Author

Owner

@N7K4 commented on GitHub (Apr 28, 2020):

@nschonni Thanks for your hint, that was a copy & paste error :-) I will remove the round braces.

@N7K4 commented on GitHub (Apr 28, 2020): @nschonni Thanks for your hint, that was a copy & paste error :-) I will remove the round braces.

kerem commented

2026-03-03 01:24:58 +03:00

Author

Owner

@DavidAnson commented on GitHub (Apr 28, 2020):

That's a good observation, thanks @nschonni. Though it doesn't affect the behavior here and I think it's by design per my comment above.

@DavidAnson commented on GitHub (Apr 28, 2020): That's a good observation, thanks @nschonni. Though it doesn't affect the behavior here and I think it's by design per my comment above.

kerem referenced this issue

2026-03-07 20:04:02 +03:00

[GH-ISSUE #232] HTML checking in MD docs #2048