starred/markdownlint

Fork 0

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

[GH-ISSUE #1771] False positive for MD051 when header contains a colon #744

New issue

Closed

opened 2026-03-03 01:29:31 +03:00 by kerem · 3 comments

kerem commented

2026-03-03 01:29:31 +03:00

Owner

Originally created by @cdwilson on GitHub (Sep 23, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1771

test.md produces a false positive for MD051:

# Overview

- [Overview](#overview)
  - [A heading with:a colon](#a-heading-witha-colon)

## A heading with:a colon

Some more text

❯ markdownlint-cli2 test.md
markdownlint-cli2 v0.18.1 (markdownlint v0.38.0)
Finding: test.md
Linting: 1 file(s)
Summary: 1 error(s)
test.md:4:5 MD051/link-fragments Link fragments should be valid [Context: "[A heading with:a colon](#a-heading-witha-colon)"]

Removing the colon from the header in test2.md:

# Overview

- [Overview](#overview)
  - [A heading without a colon](#a-heading-without-a-colon)

## A heading without a colon

Some more text

❯ markdownlint-cli2 test2.md
markdownlint-cli2 v0.18.1 (markdownlint v0.38.0)
Finding: test.md
Linting: 1 file(s)
Summary: 0 error(s)

Originally created by @cdwilson on GitHub (Sep 23, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1771 `test.md` produces a false positive for MD051: ```md # Overview - [Overview](#overview) - [A heading with:a colon](#a-heading-witha-colon) ## A heading with:a colon Some more text ``` ``` ❯ markdownlint-cli2 test.md markdownlint-cli2 v0.18.1 (markdownlint v0.38.0) Finding: test.md Linting: 1 file(s) Summary: 1 error(s) test.md:4:5 MD051/link-fragments Link fragments should be valid [Context: "[A heading with:a colon](#a-heading-witha-colon)"] ``` Removing the colon from the header in `test2.md`: ```md # Overview - [Overview](#overview) - [A heading without a colon](#a-heading-without-a-colon) ## A heading without a colon Some more text ``` ``` ❯ markdownlint-cli2 test2.md markdownlint-cli2 v0.18.1 (markdownlint v0.38.0) Finding: test.md Linting: 1 file(s) Summary: 0 error(s) ```

kerem

2026-03-03 01:29:31 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:29:32 +03:00

Author

Owner

@DavidAnson commented on GitHub (Sep 23, 2025):

In your example, the text ":a" is recognized by the Markdown parser as a directive. You can see that in the output from the demo app:

https://dlaa.me/markdownlint/#%25m%23%20Overview%0A%0A%23%23%20A%20heading%20with%3Aa%20colon%0A%0A%5BA%20heading%20with%3Aa%20colon%5D(%23a-heading-witha-colon)%0A%0A%23%23%20A%20heading%20with%5C%3Aa%20escaped%20colon%0A%0A%5BA%20heading%20with%3Aa%20escaped%20colon%5D(%23a-heading-witha-escaped-colon)%0A

You can read more about directive syntax here: https://github.com/micromark/micromark-extension-directive

While your environment may not support directives, they're enabled and recognized by default by markdownlint. Per my example above, you can backslash-escape the colon character to avoid the unwanted warning. Or you can disable the rule for that line, file, or project.

@DavidAnson commented on GitHub (Sep 23, 2025): In your example, the text ":a" is recognized by the Markdown parser as a directive. You can see that in the output from the demo app: <https://dlaa.me/markdownlint/#%25m%23%20Overview%0A%0A%23%23%20A%20heading%20with%3Aa%20colon%0A%0A%5BA%20heading%20with%3Aa%20colon%5D(%23a-heading-witha-colon)%0A%0A%23%23%20A%20heading%20with%5C%3Aa%20escaped%20colon%0A%0A%5BA%20heading%20with%3Aa%20escaped%20colon%5D(%23a-heading-witha-escaped-colon)%0A> You can read more about directive syntax here: https://github.com/micromark/micromark-extension-directive While your environment may not support directives, they're enabled and recognized by default by `markdownlint`. Per my example above, you can backslash-escape the colon character to avoid the unwanted warning. Or you can disable the rule for that line, file, or project.

kerem commented

2026-03-03 01:29:32 +03:00

Author

Owner

@cdwilson commented on GitHub (Sep 23, 2025):

Thanks for the context and the example!

Per my example above, you can backslash-escape the colon character to avoid the unwanted warning.

I ran across this today when I was trying to lint a table-of-contents generated by https://github.com/hukkin/mdformat-toc

For example, running the following doc through mdformat:

# Overview

<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=1 -->

## A heading with\:a colon

Some more text

Produces this output:

# Overview

<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=1 -->

- [Overview](#overview)
  - [A heading with:a colon](#a-heading-witha-colon)

<!-- mdformat-toc end -->

## A heading with:a colon

Some more text

From your comment, it sounds like mdformat should not remove the escape in the heading when it formats the doc. I'll open an issue in the mdformat-toc repo.

@cdwilson commented on GitHub (Sep 23, 2025): Thanks for the context and the example! > Per my example above, you can backslash-escape the colon character to avoid the unwanted warning. I ran across this today when I was trying to lint a table-of-contents generated by https://github.com/hukkin/mdformat-toc For example, running the following doc through `mdformat`: ```md # Overview  ## A heading with\:a colon Some more text ``` Produces this output: ```md # Overview  - [Overview](#overview) - [A heading with:a colon](#a-heading-witha-colon)  ## A heading with:a colon Some more text ``` From your comment, it sounds like `mdformat` should not remove the escape in the heading when it formats the doc. I'll open an issue in the `mdformat-toc` repo.

kerem commented

2026-03-03 01:29:32 +03:00

Author

Owner

@DavidAnson commented on GitHub (Sep 23, 2025):

I'm not sure I'd say they are WRONG to do so because directives are not part of the official CommonMark specification, but it IS inconvenient here and they may not need to be doing so. :)

@DavidAnson commented on GitHub (Sep 23, 2025): I'm not sure I'd say they are WRONG to do so because directives are not part of the official CommonMark specification, but it IS inconvenient here and they may not need to be doing so. :)

kerem referenced this issue

2026-03-03 02:01:23 +03:00

[PR #744] [MERGED] Bump eslint-plugin-jsdoc from 40.0.1 to 40.0.2 #984

kerem referenced this issue

2026-03-07 20:10:48 +03:00

[PR #744] [MERGED] Bump eslint-plugin-jsdoc from 40.0.1 to 40.0.2 #2836