[GH-ISSUE #1678] New Rule: Order of List + Heading = 1. List 2. Heading

kerem commented

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

Owner

Originally created by @Malix-Labs on GitHub (Jul 14, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1678

Numbered headings doesn't seem to have a standard, but there is two ways of doing them

The GitHub renderer seems to correctly parse the semantic (but also does not adjust the font size) of a List, then a Heading:

1. ## First Part

Body of the first part

2. ## Second Part

Body of the second part
First Part

Body of the first part

Second Part

Body of the second part

But seems to not correctly parse the semantic (but also does adjust the font size) of a Heading, then a List:

## 1. First Part

Body of the first part

## 2. Second Part

Body of the second part
1. First Part

Body of the first part

2. Second Part

Body of the second part

I do not know if that is in the standard markdown spec,
But it might be worth creating a new rule for it

Originally created by @Malix-Labs on GitHub (Jul 14, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1678  Numbered headings doesn't seem to have a standard, but there is two ways of doing them The GitHub renderer seems to correctly parse the semantic (but also does not adjust the font size) of a List, then a Heading: > ```md > 1. ## First Part > > Body of the first part > > 2. ## Second Part > > Body of the second part > ``` > > 1. ## First Part > > Body of the first part > > 2. ## Second Part > > Body of the second part But seems to not correctly parse the semantic (but also does adjust the font size) of a Heading, then a List: > ```md > ## 1. First Part > > Body of the first part > > ## 2. Second Part > > Body of the second part > ``` > > ## 1. First Part > > Body of the first part > > ## 2. Second Part > > Body of the second part I do not know if that is in the standard markdown spec, But it might be worth creating a new rule for it

kerem

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

closed this issue
added the
question
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Jul 14, 2025):

I'm not sure this construct makes a lot of sense in either form. I'd guess this is quite rare in practice. Perhaps a rule could exist to discourage both forms, but I don't think I see a lot of value if it's already something people don't do?

@DavidAnson commented on GitHub (Jul 14, 2025): I'm not sure this construct makes a lot of sense in either form. I'd guess this is quite rare in practice. Perhaps a rule could exist to discourage both forms, but I don't think I see a lot of value if it's already something people don't do?

kerem commented

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

Author

Owner

@Malix-Labs commented on GitHub (Jul 15, 2025):

I see numbered headings quite often personally

i.e. yesterday, I encountered it in the Markdown form of AGPL v3

@Malix-Labs commented on GitHub (Jul 15, 2025): I see numbered headings quite often personally i.e. yesterday, I encountered it in [the Markdown form of AGPL v3](https://www.gnu.org/licenses/agpl-3.0.md)

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Jul 15, 2025):

That document you link to is Markdown in the sense that all text is Markdown, but I do not think it is making any attempt to adhere to basic Markdown conventions.

In your example, it looks to me like someone wanted to emphasize the numbered sections of an existing text document and just made them all headings.

Here's another example, a sequence of unordered list items containing a single ordered list item each:

provided that you also meet all of these conditions:

-   a) The work must carry prominent ...

I do not want to make too many decisions based on scenarios like this that feel like Markdown in name only.

@DavidAnson commented on GitHub (Jul 15, 2025): That document you link to is Markdown in the sense that all text is Markdown, but I do not think it is making any attempt to adhere to basic Markdown conventions. In your example, it looks to me like someone wanted to emphasize the numbered sections of an existing text document and just made them all headings. Here's another example, a sequence of unordered list items containing a single ordered list item each: ``` provided that you also meet all of these conditions: - a) The work must carry prominent ... ``` I do not want to make too many decisions based on scenarios like this that feel like Markdown in name only.

kerem commented

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

Author

Owner

@Malix-Labs commented on GitHub (Jul 15, 2025):

This is true indeed

However, I think numbered headings are still valuable

They are especially common for legal or legislative (non-markdown) documents

@Malix-Labs commented on GitHub (Jul 15, 2025): This is true indeed However, I think numbered headings are still valuable They are especially common for legal or legislative (non-markdown) documents

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Jul 15, 2025):

FYI, headings that begin with a list item-like number are not treated as ordered or unordered lists per the CommonMark specification.

Specifically, the body of an ATX list is parsed as inline content which excludes list items (which are container blocks): https://spec.commonmark.org/0.31.2/#atx-headings

Corresponding example using the dingus: https://spec.commonmark.org/dingus/?text=%23%201.%20Test%0A%0A

@DavidAnson commented on GitHub (Jul 15, 2025): FYI, headings that begin with a list item-like number are not treated as ordered or unordered lists per the CommonMark specification. Specifically, the body of an ATX list is parsed as inline content which excludes list items (which are container blocks): https://spec.commonmark.org/0.31.2/#atx-headings Corresponding example using the dingus: https://spec.commonmark.org/dingus/?text=%23%201.%20Test%0A%0A

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Jul 15, 2025):

List items can explicitly include headings: https://spec.commonmark.org/0.31.2/#example-300

@DavidAnson commented on GitHub (Jul 15, 2025): List items can explicitly include headings: https://spec.commonmark.org/0.31.2/#example-300

kerem commented

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

Author

Owner

@Malix-Labs commented on GitHub (Jul 15, 2025):

List items can explicitly include headings: spec.commonmark.org/0.31.2#example-300

Indeed;
Thus:

A List, then a Heading:

1. ## First Part

Body of the first part

2. ## Second Part

Body of the second part
First Part

Body of the first part

Second Part

Body of the second part

Is correct

While a Heading, then a List:

## 1. First Part

Body of the first part

## 2. Second Part

Body of the second part
1. First Part

Body of the first part

2. Second Part

Body of the second part

Is incorrect

@Malix-Labs commented on GitHub (Jul 15, 2025): > List items can explicitly include headings: [spec.commonmark.org/0.31.2#example-300](https://spec.commonmark.org/0.31.2/#example-300) Indeed; Thus: A List, then a Heading: > ```md > 1. ## First Part > > Body of the first part > > 2. ## Second Part > > Body of the second part > ``` > > 1. ## First Part > > Body of the first part > > 2. ## Second Part > > Body of the second part Is correct While a Heading, then a List: > ```md > ## 1. First Part > > Body of the first part > > ## 2. Second Part > > Body of the second part > ``` > > ## 1. First Part > > Body of the first part > > ## 2. Second Part > > Body of the second part Is incorrect

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Jul 15, 2025):

What do you mean by "correct" and "incorrect"? These are two different structures with (seemingly) defined behavior. Putting large blocks of content inside a list has different implications than having numbered headings, but I'm not sure I'd say either is obviously better in the abstract or in what scenarios one or the other is inappropriate.

@DavidAnson commented on GitHub (Jul 15, 2025): What do you mean by "correct" and "incorrect"? These are two different structures with (seemingly) defined behavior. Putting large blocks of content inside a list has different implications than having numbered headings, but I'm not sure I'd say either is obviously better in the abstract or in what scenarios one or the other is inappropriate.

kerem commented

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

Author

Owner

@Malix-Labs commented on GitHub (Oct 4, 2025):

Have you tested how the vast majority of markdown processors handle them?

@Malix-Labs commented on GitHub (Oct 4, 2025): Have you tested how the vast majority of markdown processors handle them?

kerem referenced this issue

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

[GH-ISSUE #733] MD052 and brackets #2373

Rows
Columns

[GH-ISSUE #1678] New Rule: Order of List + Heading = 1. List 2. Heading #733

First Part

Second Part

1. First Part

2. Second Part

First Part

Second Part

1. First Part

2. Second Part