[GH-ISSUE #1267] MD036: doesn't fire when any HTML comment is present on the same line. #2498

New issue

Closed

opened 2026-03-07 20:08:19 +03:00 by kerem · 0 comments

kerem commented

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

Owner

Originally created by @wwarriner on GitHub (Jun 21, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1267

Hey there, appreciate the linter and associated tooling and am using it for pre-commit hooks and CI/CD in our organization's documentation. Thank you!

I've discovered that MD036 doesn't fire when any HTML comment is present on the same line. I do not know if this is intended behavior and could not determine based on a cursory search of past issues (searching for MD036) nor the docs.

The rationale for MD036 says "Using emphasis instead of a heading prevents tools from inferring the structure of a document." If an HTML comment prevents this rule from firing, then the rationale is not achieved, as the comment should have no impact on inference. Unless there is tooling that uses comments to infer document structure? I honestly don't know, but it would surprise me.

To reproduce, create a markdown document with the following.

# Header

**Triggers MD036**

**Does not trigger MD036** <!-- -->

The output should look like the following, noting that line 5 is not present in the output.

markdownlint-cli2 v0.13.0 (markdownlint v0.34.0)
Finding: ./docs/test.md
Linting: 1 file(s)
Summary: 1 error(s)
docs/test.md:3 MD036/no-emphasis-as-heading Emphasis used instead of a heading [Context: "Triggers MD036"]

I hope this is helpful.

Originally created by @wwarriner on GitHub (Jun 21, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1267 Hey there, appreciate the linter and associated tooling and am using it for pre-commit hooks and CI/CD in our organization's documentation. Thank you! I've discovered that MD036 doesn't fire when any HTML comment is present on the same line. I do not know if this is intended behavior and could not determine based on a cursory search of past issues (searching for MD036) nor the docs. The rationale for MD036 says "Using emphasis instead of a heading prevents tools from inferring the structure of a document." If an HTML comment prevents this rule from firing, then the rationale is not achieved, as the comment should have no impact on inference. Unless there is tooling that uses comments to infer document structure? I honestly don't know, but it would surprise me. To reproduce, create a markdown document with the following. ``` # Header **Triggers MD036** **Does not trigger MD036**  ``` The output should look like the following, noting that line 5 is not present in the output. ``` markdownlint-cli2 v0.13.0 (markdownlint v0.34.0) Finding: ./docs/test.md Linting: 1 file(s) Summary: 1 error(s) docs/test.md:3 MD036/no-emphasis-as-heading Emphasis used instead of a heading [Context: "Triggers MD036"] ``` I hope this is helpful.