single-h1 #169

New issue

Closed

opened 2026-03-03 01:24:21 +03:00 by kerem · 3 comments

kerem commented

2026-03-03 01:24:21 +03:00

Owner

Originally created by @AliceonFire on GitHub (Jun 15, 2019).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/199

The MD025 rule complains about "Multiple top-level headings in the same document" seemingly because there is a title in the article's YAML frontmatter along with an h1 heading in the same document. I can't think of why else the warning would appear. Is this intentional?

---
title: "How Titles and Headings Affect SEO | SEOMasters"
---

# Does Google Weigh Title and H1 Equally?

## the answer may surprise you…

Single opinions such as MD026/no-trailing-punctuation can be disregarded easily enough, but it seems MD025 could be useful with separation of the single-title and single-h1 rules. Would it be possible to toggle this decoupling in a setting rather than turning the rule off entirely?

Originally created by @AliceonFire on GitHub (Jun 15, 2019). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/199 The **MD025** rule complains about *"Multiple top-level headings in the same document"* seemingly because there is a title in the article's YAML frontmatter along with an h1 heading in the same document. I can't think of why else the warning would appear. Is this intentional? ``` --- title: "How Titles and Headings Affect SEO | SEOMasters" --- # Does Google Weigh Title and H1 Equally? ## the answer may surprise you… ``` Single opinions such as **MD026/no-trailing-punctuation** can be disregarded easily enough, but it seems MD025 could be useful with separation of the single-title and single-h1 rules. Would it be possible to toggle this decoupling in a setting rather than turning the rule off entirely?

kerem

2026-03-03 01:24:21 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:24:22 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 15, 2019):

This is deliberate (for the reason you suggest) and is customizable. The rule documentation explains more: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md025---multiple-top-level-headings-in-the-same-document

@DavidAnson commented on GitHub (Jun 15, 2019): This is deliberate (for the reason you suggest) and is customizable. The rule documentation explains more: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md025---multiple-top-level-headings-in-the-same-document

kerem commented

2026-03-03 01:24:22 +03:00

Author

Owner

@AliceonFire commented on GitHub (Jun 15, 2019):

The MD025 rule documentation states To disable the use of front matter by this rule, specify "" for front_matter_title.

This is not seen as a valid editor configuration setting:

{
    "[markdown]":{
        "front_matter_title": ""
    }
}

Placing it within a markdown file's YAML frontmatter also has no effect:

---
front_matter_title: ""
title: "Page Title"
---

# Page Header

Where is the specification of "front_matter_title" to be carried out?

@AliceonFire commented on GitHub (Jun 15, 2019): The **MD025** rule documentation states `To disable the use of front matter by this rule, specify "" for front_matter_title.` This is not seen as a valid editor configuration setting: ```json { "[markdown]":{ "front_matter_title": "" } } ``` Placing it within a markdown file's YAML frontmatter also has no effect: ```markdown --- front_matter_title: "" title: "Page Title" --- # Page Header ``` Where is the specification of "front_matter_title" to be carried out?

kerem commented

2026-03-03 01:24:23 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 15, 2019):

This part of the documentation outlines what the configuration object should look like: https://github.com/DavidAnson/markdownlint#optionsconfig

Rule parameters are nested; here is a specific example for your scenario: github.com/DavidAnson/markdownlint@6f7c0aac13/test/hugo-quickstart-example-clean.json

Just in case you are using the VS Code extension, here's what things looks like in the configuration for that editor: https://github.com/DavidAnson/vscode-markdownlint#markdownlintconfig

@DavidAnson commented on GitHub (Jun 15, 2019): This part of the documentation outlines what the configuration object should look like: https://github.com/DavidAnson/markdownlint#optionsconfig Rule parameters are nested; here is a specific example for your scenario: https://github.com/DavidAnson/markdownlint/blob/6f7c0aac131f21dd41a2a26810779c993521b733/test/hugo-quickstart-example-clean.json Just in case you are using the VS Code extension, here's what things looks like in the configuration for that editor: https://github.com/DavidAnson/vscode-markdownlint#markdownlintconfig

kerem referenced this issue

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

[GH-ISSUE #116] MD041/first-line-h1 complains despite title attribute in frontmatter #1946

kerem referenced this issue

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

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