[GH-ISSUE #169] MD002 rule reports inconsistent error

kerem commented

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

Owner

Originally created by @amimas on GitHub (Mar 8, 2019).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/169

I am using a static site generator where I have frontmatter yaml like this:

---
id: index
title: Title of my page
---

The title is converted into H1 when the html page is created. So, in my case I don't need the first heading in the markdown to be a H1. That's why I've configured the following rules:

{
  "default": true,
  "MD002": { "level": 2 }
  "MD041": false
}

This seems to be working fine. If the very first heading in the content starts with anything other than H2, then I get the following error message:

../docs/index.md: 7: MD002/first-heading-h1/first-header-h1 First heading should be a top level heading [Expected: h2; Actual: h1]
../docs/index.md: 7: MD002/first-heading-h1/first-header-h1 First heading should be a top level heading [Expected: h2; Actual: h3]

I believe I am getting the right behaviour (or at least what I expect), but the error message is slightly conflicting/confusing. At the beginning the error says first-heading-h1 but later it says h2 is expected.

Originally created by @amimas on GitHub (Mar 8, 2019). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/169 I am using a static site generator where I have frontmatter yaml like this: ```yml --- id: index title: Title of my page --- ``` The `title` is converted into H1 when the html page is created. So, in my case I don't need the first heading in the markdown to be a H1. That's why I've configured the following rules: ```json { "default": true, "MD002": { "level": 2 } "MD041": false } ``` This seems to be working fine. If the very first heading in the content starts with anything other than H2, then I get the following error message: ``` ../docs/index.md: 7: MD002/first-heading-h1/first-header-h1 First heading should be a top level heading [Expected: h2; Actual: h1] ../docs/index.md: 7: MD002/first-heading-h1/first-header-h1 First heading should be a top level heading [Expected: h2; Actual: h3] ``` I believe I am getting the right behaviour (or at least what I expect), but the error message is slightly conflicting/confusing. At the beginning the error says *first-heading-h1* but later it says h2 is expected.

kerem

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

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

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

Author

Owner

@nschonni commented on GitHub (Mar 8, 2019):

Is their a BOM or spaces at the beginning of the file? You can usually check that if you open the file on github and the front-mater isn't rendering as a table

@nschonni commented on GitHub (Mar 8, 2019): Is their a BOM or spaces at the beginning of the file? You can usually check that if you open the file on github and the front-mater isn't rendering as a table

kerem commented

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

Author

Owner

@amimas commented on GitHub (Mar 9, 2019):

I'm not following you. The rule is working properly. The rule's label suggests the first heading must be h1 but that is configurable to be something else.

I think the rule's label needs to be phrased differently.

@amimas commented on GitHub (Mar 9, 2019): I'm not following you. The rule is working properly. The rule's label suggests the first heading must be h1 but that is configurable to be something else. I think the rule's label needs to be phrased differently.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Mar 9, 2019):

To be clear, you don't get both errors above at the same time, right? When I try your scenario on my machine, I only get one error at a time and it correctly identifies the wrong heading I used (H1 or H3). Assuming that's so, we agree the rule is working properly and your question is about the naming. Originally, MD002 was only about H1 headings and the name first-heading-h1 made sense. When I added support for the level parameter, I considered renaming, but something like first-heading-hx seemed more confusing and first-heading-h? isn't valid. Because most people leave the default of 1, it's usually correct as it is today. Do you have any suggestions to improve the name?

PS - To be more explicit, you might change your config to:

{
    "default": true,
    "MD002": { "level": 2 },
    "MD041": { "level": 2 }
}

@DavidAnson commented on GitHub (Mar 9, 2019): To be clear, you don't get both errors above at the same time, right? When I try your scenario on my machine, I only get one error at a time and it correctly identifies the wrong heading I used (H1 or H3). Assuming that's so, we agree the rule is working properly and your question is about the naming. Originally, `MD002` was only about H1 headings and the name `first-heading-h1` made sense. When I added support for the `level` parameter, I considered renaming, but something like `first-heading-hx` seemed more confusing and `first-heading-h?` isn't valid. Because most people leave the default of 1, it's usually correct as it is today. Do you have any suggestions to improve the name? PS - To be more explicit, you might change your config to: ```md { "default": true, "MD002": { "level": 2 }, "MD041": { "level": 2 } } ```

kerem commented

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

Author

Owner

@amimas commented on GitHub (Mar 9, 2019):

first-heading-hx sounds good to me. I didn't find it confusing since it indicates a specific level of header is expected to be the first header in a document.

@amimas commented on GitHub (Mar 9, 2019): `first-heading-hx` sounds good to me. I didn't find it confusing since it indicates a specific level of header is expected to be the first header in a document.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Mar 9, 2019):

After more thought, I'm leaning toward:
MD002 -> first-heading-level
MD041 -> first-line-heading

@DavidAnson commented on GitHub (Mar 9, 2019): After more thought, I'm leaning toward: MD002 -> first-heading-level MD041 -> first-line-heading

kerem commented

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

Author

Owner

@amimas commented on GitHub (Mar 11, 2019):

After more thought, I'm leaning toward:
MD002 -> first-heading-level
MD041 -> first-line-heading

I think that's a good suggestion too. But, which rule will look at title in frontmatter? Should the default configuration change based on whether frontmatter is present or not? Or, maybe forget about frontmatter since not everybody is going to use it. If anyone is using frontmatter, they will have to adjust the configuration of both rules.

@amimas commented on GitHub (Mar 11, 2019): > After more thought, I'm leaning toward: MD002 -> first-heading-level MD041 -> first-line-heading I think that's a good suggestion too. But, which rule will look at `title` in frontmatter? Should the default configuration change based on whether frontmatter is present or not? Or, maybe forget about frontmatter since not everybody is going to use it. If anyone is using frontmatter, they will have to adjust the configuration of both rules.

kerem commented

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

Author

Owner

@amimas commented on GitHub (Mar 11, 2019):

With the above proposal, how do we enforce MD025 (multiple top level header is not allowed). Please let me know if I should open a separate issue for this.

@amimas commented on GitHub (Mar 11, 2019): With the above proposal, how do we enforce MD025 (multiple top level header is not allowed). Please let me know if I should open a separate issue for this.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Mar 11, 2019):

41 is a stricter version than 2 and supports front matter. The only thing 2 offers is not starting the file with an h1 - I think starting with a header is a good practice and reducing the duplication is good. My plan is to remove 2 and leave 41 as it is after the change from #116.

I’m not sure 25 needs to change. The possible problem would be if a file had a title and an h1, but even then that’s not multiple h1’s. Do you have something else in mind?

@DavidAnson commented on GitHub (Mar 11, 2019): 41 is a stricter version than 2 and supports front matter. The only thing 2 offers is not starting the file with an h1 - I think starting with a header is a good practice and reducing the duplication is good. My plan is to remove 2 and leave 41 as it is after the change from #116. I’m not sure 25 needs to change. The possible problem would be if a file had a title and an h1, but even then that’s not multiple h1’s. Do you have something else in mind?

kerem commented

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

Author

Owner

@amimas commented on GitHub (Mar 11, 2019):

I like your proposal of:

MD002 -> first-heading-level
MD041 -> first-line-heading

I'm just not sure how to enforce "not allowing an h1" when I have a frontmatter with a title field like this because the title is equivalent to an H1 and a page should not have multiple H1/top-level heading (MD025).

---
id: index
title: Title of my page
---

@amimas commented on GitHub (Mar 11, 2019): I like your proposal of: > MD002 -> first-heading-level > MD041 -> first-line-heading I'm just not sure how to enforce "not allowing an h1" when I have a frontmatter with a `title` field like this because the title is equivalent to an H1 and a page should not have multiple H1/top-level heading (MD025). ``` --- id: index title: Title of my page --- ```

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Mar 11, 2019):

I think your scenario would be possible if MD025 was given knowledge of front matter/title?

@DavidAnson commented on GitHub (Mar 11, 2019): I think your scenario would be possible if MD025 was given knowledge of front matter/title?

kerem commented

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

Author

Owner

@amimas commented on GitHub (Mar 11, 2019):

I think your scenario would be possible if MD025 was given knowledge of front matter/title?

Agreed. Does that exist today?

@amimas commented on GitHub (Mar 11, 2019): > I think your scenario would be possible if MD025 was given knowledge of front matter/title? Agreed. Does that exist today?

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Mar 12, 2019):

Not yet.

@DavidAnson commented on GitHub (Mar 12, 2019): Not yet.

kerem referenced this issue

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

[PR #1993] [MERGED] Update test repository snapshots. #3698

Rows
Columns

[GH-ISSUE #169] MD002 rule reports inconsistent error #1993