feat: add no-heading-like-paragraph rule by Gaic4o · Pull Request #716 · eslint/markdown

Gaic4o · 2026-08-16T07:48:01Z

Prerequisites checklist

I have read the contributing guidelines.

AI acknowledgment

I did not use AI to generate this PR.
(If the above is not checked) I have reviewed the AI-generated content before submitting.

What is the purpose of this pull request?

This PR implements the no-heading-like-paragraph rule proposed and accepted in #700.

CommonMark ATX headings support at most six # characters. As a result, content such as ####### Installation is parsed as a paragraph rather than a heading, even though it can easily look like an intended heading in the source.

The rule reports these heading-like paragraphs so that likely heading mistakes can be identified.

What changes did you make? (Give an overview)

Added the no-heading-like-paragraph rule for paragraphs that look like ATX headings with seven or more leading # characters.
The rule checks the raw source to avoid false positives for escaped or character-referenced input.
Added suggestions to either convert the paragraph to a valid level-6 heading or escape the first # to keep it as a paragraph.
No automatic fix is provided because the author's intent is ambiguous.

Related Issues

fixes #700

Disclosure: I'm a participant of open source contribution program OSSCA

lumirlumir

Disclosure: I'm a participant of open source contribution program OSSCA: confirmed.

Can you take a look at the CI failure? Running npm run fmt should resolve the problem.

lumirlumir · 2026-08-17T10:06:14Z

+const gfmRuleTester = new RuleTester({
+	plugins: {
+		markdown,
+	},
+	language: "markdown/gfm",
+});


I think we can use language: "markdown/gfm" where necessary to test GFM mode, as shown below. Consolidating these RuleTester test cases with the ones above also seems helpful.

markdown/tests/rules/no-missing-label-refs.test.js

Lines 126 to 131 in ac31775

code: dedent`

- [x] Checked

- [-] In progress

`,

language: "markdown/gfm",

options: [{ allowLabels: ["-"] }],

Integrated the GFM cases into the existing RuleTester as suggested.

lumirlumir · 2026-08-17T10:09:50Z

+		type: "problem",
+
+		docs: {
+			recommended: false,


Suggested change

recommended: false,

Non-blocking stylistic choice: The repository usually omits the recommended field when it is false.

Removed recommended: false to match the existing repository style. Thanks!

lumirlumir · 2026-08-17T10:23:44Z

+					endColumn: 8,
+					suggestions: [
+						{
+							messageId: "useMaxDepthHashes",


Could you add the missing data properties to the invalid test cases? This applies to all other invalid test cases as well.

Added the required data properties to all invalid test cases.

DMartens · 2026-08-17T21:54:55Z

+Seven ####### characters in the middle of a paragraph.
+```
+
+This rule only checks the beginning of a paragraph, so it ignores hash characters on a continuation line:


This case should still be handled by the rule as the writer expects to create a heading (which would be created if it would use valid heading syntax).
This could be accomplished by setting the m(ultiline) flag for headingLikeParagraphPattern.

I agree. I’ll update the rule to handle continuation lines as well. I think this will also keep it consistent with no-missing-atx-heading-space.

However, since the m flag alone can miss continuation lines inside blockquotes or list items, would it be okay to handle those container cases as well as the top-level case and add tests for them?

I do not think we need to check for continuation lines inside a container (like blockquotes).
What do you think @lumirlumir?

DMartens · 2026-08-17T22:02:44Z

+				 * the author escaped the leading hash on purpose.
+				 */
+				const match = headingLikeParagraphPattern.exec(
+					sourceCode.getText(node),


Suggested change

sourceCode.getText(node),

sourceCode.getText(node.children[0]),

Why not use just the first child. This would make the text potentially smaller which is always good when using regular expressions.

Using only the first child could introduce false positives when inline markup immediately follows the hashes. For example, in the current valid test case #######*Installation*, the source of the first child ends with #######, so the $ condition in the regular expression could match. However, in the full paragraph source, the hashes are followed by *, so it does not satisfy the ATX heading delimiter condition.

Also, checking only the first child would not be sufficient for handling continuation lines discussed in the other thread. For example, in Install **first**.\n####### Config, the heading-like text can be contained in a later child rather than the first one, so this case would be missed.

For correctness, I think matching against the whole paragraph source is safer than checking only the first child.

For this edge case you can pass afterCount to get also the following characters, so
sourceCode.getText(node.children[0], 0, 1).

DMartens · 2026-08-17T22:04:04Z

+			],
+		},
+		{
+			code: "#######",


I do not think this should be an invalid test case as the text after the hashes are missing.
Some may use thisas decoration.

That makes sense. If there’s no text after the hashes, I agree that it’s much less clear whether the author actually intended to create a heading. For reference, remark-lint-no-heading-like-paragraph does report a bare #######, but I agree that this case could reasonably be treated as decoration.

I’d just like to clarify the intended scope. Should cases like ####### , where the hashes are followed only by trailing whitespace, and #######\nText, where the first line of a multi-line paragraph contains only the hashes, also be ignored? Or should only the single-line bare ####### case be excluded?

DMartens · 2026-08-17T22:05:04Z

+					messageId: "headingLikeParagraph",
+					data: { count: hashes.length },
+
+					/*


This comment is unnecessary as two suggestions are provided, it is clear that there can be no autofix.

I removed the unnecessary comment as you suggested. Thank you!

feat: add no-heading-like-paragraph rule

8d97505

eslint-github-bot Bot added the feature label Aug 16, 2026

eslint-github-bot Bot mentioned this pull request Aug 16, 2026

New Rule: no-heading-like-paragraph #700

Open

3 tasks

eslintbot added this to Triage Aug 16, 2026

github-project-automation Bot moved this to Needs Triage in Triage Aug 16, 2026

lumirlumir added the accepted label Aug 17, 2026

lumirlumir moved this from Needs Triage to Triaging in Triage Aug 17, 2026

lumirlumir requested changes Aug 17, 2026

View reviewed changes

lumirlumir moved this from Triaging to Implementing in Triage Aug 17, 2026

DMartens reviewed Aug 17, 2026

View reviewed changes

fix: apply review feedback

bfd826f

Gaic4o requested review from DMartens and lumirlumir August 19, 2026 06:42

	code: dedent`
	- [x] Checked
	- [-] In progress
	`,
	language: "markdown/gfm",
	options: [{ allowLabels: ["-"] }],

	sourceCode.getText(node),
	sourceCode.getText(node.children[0]),

Uh oh!

Conversation

Gaic4o commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Prerequisites checklist

AI acknowledgment

What is the purpose of this pull request?

What changes did you make? (Give an overview)

Related Issues

Uh oh!

lumirlumir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DMartens Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Gaic4o commented Aug 16, 2026 •

edited

Loading

DMartens Aug 17, 2026 •

edited

Loading