[GH-ISSUE #377] MD025 Error when using front_matter_title and h1

kerem commented

2026-03-03 01:25:40 +03:00

Owner

Originally created by @redtux on GitHub (Mar 24, 2021).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/377

Hi, when using title in a YAML frontmatter (aka metadata block) the first heading h1 throws a linting error for rules MD025 and MD043. When omitting h1, the top heading h2 throws error MD043.

front_matter_title: "^\\s*title\\s*[:=]" is set for MD025 and for MD041. Rule MD041 is working fine, as it throws no error. (Just in case: Setting front_matter_title: "" for MD025 in my .markdownlint.yaml is not changing anything.)

NB: I have read both the Readme and the Rules.md doc, and I had a look at known issues.

The expected behavior would be a) to be able to use both a frontmatter title block and a # First Heading together, or b) to be able to omit the # First Heading when using title inside a frontmatter.

As I found no solution to this, it might be a bug in the linter specs – or this (intended?) limitation should at least be (better) described in the docs.

The issue has also been described here: https://github.com/microsoft/vscode-docs-authoring/pull/269

Originally created by @redtux on GitHub (Mar 24, 2021). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/377 Hi, when using `title` in a YAML frontmatter (aka metadata block) the first heading `h1` throws a linting error for rules `MD025` and `MD043`. When omitting `h1`, the top heading `h2` throws error `MD043`. `front_matter_title: "^\\s*title\\s*[:=]"` is set for `MD025` and for `MD041`. Rule `MD041` is working fine, as it throws no error. (Just in case: Setting `front_matter_title: ""` for `MD025` in my `.markdownlint.yaml` is not changing anything.) NB: I have read both the Readme and the `Rules.md` doc, and I had a look at [known issues](https://github.com/DavidAnson/markdownlint/issues?q=is%3Aissue+frontmatter+). The expected behavior would be a) to be able to use both a frontmatter title block and a `# First Heading` together, or b) to be able to omit the `# First Heading` when using `title` inside a frontmatter. As I found no solution to this, it might be a bug in the linter specs – or this (intended?) limitation should at least be (better) described in the docs. The issue has also been described here: https://github.com/microsoft/vscode-docs-authoring/pull/269

kerem

2026-03-03 01:25:40 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:25:41 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 24, 2021):

It sounds like you are describing this scenario in which case it sounds like you are seeing the expected behavior: https://github.com/DavidAnson/markdownlint/blob/main/test/front-matter-title-h1.md

If the YAML front matter includes a title, then the H1 element is redundant - as would be a top-level Markdown heading.

If your scenario is different, please provide example Markdown and explain what you expect.

@DavidAnson commented on GitHub (Mar 24, 2021): It sounds like you are describing this scenario in which case it sounds like you are seeing the expected behavior: https://github.com/DavidAnson/markdownlint/blob/main/test/front-matter-title-h1.md If the YAML front matter includes a title, then the H1 element is redundant - as would be a top-level Markdown heading. If your scenario is different, please provide example Markdown and explain what you expect.

kerem commented

2026-03-03 01:25:41 +03:00

Author

Owner

@redtux commented on GitHub (Mar 24, 2021):

This is the scenario, but as explained when not using the H1 element I get an error with the first H2 element.

@redtux commented on GitHub (Mar 24, 2021): This is the scenario, but as explained when not using the H1 element I get an error with the first H2 element.

kerem commented

2026-03-03 01:25:41 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 24, 2021):

OK, it seems we agree this scenario should generate an MD025 error due to two top-level headings: https://dlaa.me/markdownlint/#%25m---%0Atitle%3A%20%20%22Hello%20world%22%0A---%0A%23%20Top%20level%20heading%0A

Switching the second of those to a second-level heading generates no errors: https://dlaa.me/markdownlint/#%25m---%0Atitle%3A%20%20%22Hello%20world%22%0A---%0A%23%23%20Second%20level%20heading%0A

Is that not what you are seeing?

@DavidAnson commented on GitHub (Mar 24, 2021): OK, it seems we agree this scenario should generate an MD025 error due to two top-level headings: https://dlaa.me/markdownlint/#%25m---%0Atitle%3A%20%20%22Hello%20world%22%0A---%0A%23%20Top%20level%20heading%0A Switching the second of those to a second-level heading generates no errors: https://dlaa.me/markdownlint/#%25m---%0Atitle%3A%20%20%22Hello%20world%22%0A---%0A%23%23%20Second%20level%20heading%0A Is that not what you are seeing?

kerem commented

2026-03-03 01:25:41 +03:00

Author

Owner

@redtux commented on GitHub (Mar 24, 2021):

This is what I would expect, but in the second scenario (title inside frontmatter followed by ## H2 outside the frontmatter block) it throws MD043 as error (saying [Expected]: [None]). Do I need to specify a specific list of headings in my config? At the moment I have an empty array (which seemed okay to me).

@redtux commented on GitHub (Mar 24, 2021): This is what I would expect, but in the second scenario (title inside frontmatter followed by `## H2` outside the frontmatter block) it throws MD043 as error (saying `[Expected]: [None]`). Do I need to specify a specific list of headings in my config? At the moment I have an empty array (which seemed okay to me).

kerem commented

2026-03-03 01:25:41 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 24, 2021):

It sounds like your configuration for MD043 is saying that you require there to be no headers (i.e., an empty list/array) in your document. Therefore, the presence of the second level header is a violation. If you want there to be headers, you will need to specify them for MD043 as shown in the documentation. If you do not want to validate headers, you can leave MD043 alone (by default it makes no requirements), turn it off, or pass null for the list (if I recall correctly).

https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md043

@DavidAnson commented on GitHub (Mar 24, 2021): It sounds like your configuration for MD043 is saying that you require there to be no headers (i.e., an empty list/array) in your document. Therefore, the presence of the second level header is a violation. If you want there to be headers, you will need to specify them for MD043 as shown in the documentation. If you do not want to validate headers, you can leave MD043 alone (by default it makes no requirements), turn it off, or pass null for the list (if I recall correctly). https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md043

kerem commented

2026-03-03 01:25:41 +03:00

Author

Owner

@redtux commented on GitHub (Mar 24, 2021):

Thank you for your kind help! This means that I have to specify each heading like shown here?
https://github.com/DavidAnson/vscode-markdownlint/blob/main/.markdownlint.json#L6

@redtux commented on GitHub (Mar 24, 2021): Thank you for your kind help! This means that I have to specify each heading like shown here? https://github.com/DavidAnson/vscode-markdownlint/blob/main/.markdownlint.json#L6

kerem commented

2026-03-03 01:25:41 +03:00

Author

Owner

@redtux commented on GitHub (Mar 24, 2021):

Okay, using a wildcard as described in the documentation (or setting MD043: false) works fine.

# MD043/required-headings/required-headers - Required heading structure
MD043:
  # List of headings
  headings: ["*"]
  # List of headings
  headers: []

Looks like I just cannot have it both ways, so I close this issue as the described behavior is not a bug but intended. Thanks again for the quick and concise help! 🎉

@redtux commented on GitHub (Mar 24, 2021): Okay, using a wildcard as described in the documentation (or setting `MD043: false`) works fine. ``` # MD043/required-headings/required-headers - Required heading structure MD043: # List of headings headings: ["*"] # List of headings headers: [] ``` Looks like I just cannot have it both ways, so I close this issue as the described behavior is not a bug but intended. Thanks again for the quick and concise help! 🎉

kerem commented

2026-03-03 01:25:41 +03:00

Author

Owner

@Garbee commented on GitHub (Jan 10, 2022):

This exact issue is breaking the rule in https://www.11ty.dev for me. In 11ty, frontmatter is used for data, but it does not in any way directly modify page content. Everything is manually written and targeted. Thus the following code is entirely accurate and should not trigger such an error:

---
title: Some page title
---

# How to be awesome

Yet, because of this assumed context of frontmatter usage, it seems the linter is stuck on erroring when it is in fact wrong.

I think a configuration option is needed to opt-out of this assumed context. That way those of us in systems that do not automate so much are able to still use the lint rule.

Update:

Seems there is a way to bypass this documented. front_matter_title to an empty string for a config option. Just got my cli2 config working, and yes that does do the trick actually. Perhaps this config was added after this conversation?

@Garbee commented on GitHub (Jan 10, 2022): This exact issue is breaking the rule in https://www.11ty.dev for me. In 11ty, frontmatter is used for data, but it does not in any way directly modify page content. Everything is manually written and targeted. Thus the following code is entirely accurate and should not trigger such an error: ``` --- title: Some page title --- # How to be awesome ``` Yet, because of this assumed context of frontmatter usage, it seems the linter is stuck on erroring when it is in fact wrong. I think a configuration option is needed to opt-out of this assumed context. That way those of us in systems that do not automate so much are able to still use the lint rule. Update: Seems there is a way to bypass this documented. front_matter_title to an empty string for a config option. Just got my cli2 config working, and yes that does do the trick actually. Perhaps this config was added after this conversation?

kerem commented

2026-03-03 01:25:42 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jan 10, 2022):

@Garbee You can disable MD025 or configure it to not treat YAML "title" as a top-level heading.

@DavidAnson commented on GitHub (Jan 10, 2022): @Garbee You can disable MD025 or configure it to not treat YAML "title" as a top-level heading.

kerem referenced this issue

2026-03-07 20:04:46 +03:00

[GH-ISSUE #316] [New Rule Feature] Multiple blank block quote marks should be combined into one #2119

Rows
Columns

[GH-ISSUE #377] MD025 Error when using front_matter_title and h1 #316