starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 09:16:02 +03:00

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

New issue

Closed

opened 2026-03-07 20:03:01 +03:00 by kerem · 8 comments

kerem commented

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

Owner

Originally created by @stephanschubert on GitHub (Mar 24, 2018).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/116

Start of my .md file:

---
path: "/impressum"
date: "2012-06-21T10:14:00.000+02:00"
title: "Impressum"
---

## Angaben gemäß § 5 TMG

My .markdownlintrc file:

{
  "MD002": { "level": 2 },
  "MD041": { "level": 2 },
  //"MD041/first-line-h1": { "level": 2 }, <-- Tried that one too
  "MD026": { "punctuation": ".,;:" },
}

But still:

markdownlint -c ../../.markdownlintrc src/pages/imprint.md
src/pages/imprint.md: 7: MD041/first-line-h1 First line in file should be a top level header [Context: "## Angaben gemäß § 5 TMG"]

Am I missing sth or is this a bug?

Originally created by @stephanschubert on GitHub (Mar 24, 2018). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/116 Start of my `.md` file: ``` --- path: "/impressum" date: "2012-06-21T10:14:00.000+02:00" title: "Impressum" --- ## Angaben gemäß § 5 TMG ``` My `.markdownlintrc` file: ``` { "MD002": { "level": 2 }, "MD041": { "level": 2 }, //"MD041/first-line-h1": { "level": 2 }, <-- Tried that one too "MD026": { "punctuation": ".,;:" }, } ``` But still: ``` markdownlint -c ../../.markdownlintrc src/pages/imprint.md src/pages/imprint.md: 7: MD041/first-line-h1 First line in file should be a top level header [Context: "## Angaben gemäß § 5 TMG"] ``` Am I missing sth or is this a bug?

kerem

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

closed this issue
added the
bug

fixed in next
labels

kerem commented

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

Author

Owner

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

The code does respect YAML titles, but there's a subtlety that's causing this issue.

First, proof that YAML title is respected - the following does not trigger MD041:

---
path: "/impressum"
date: "2012-06-21T10:14:00.000+02:00"
title: "Impressum"
---

Hallo

## Angaben gemäß § 5 TMG

However, your example reports an issue because the first text of the document is a header. If MD041 sees a header first, it doesn't care if a front matter title is present and it reports an issue.

I'll think about whether that might be correct, but it seems wrong to me right now, so I'm calling this a bug and you can assume I will fix it in the next release.

Sorry about that!

@DavidAnson commented on GitHub (Mar 24, 2018): The code does respect YAML titles, but there's a subtlety that's causing this issue. First, proof that YAML title is respected - the following does not trigger `MD041`: ```md --- path: "/impressum" date: "2012-06-21T10:14:00.000+02:00" title: "Impressum" --- Hallo ## Angaben gemäß § 5 TMG ``` However, your example reports an issue *because the first text of the document is a header*. If `MD041` sees a header first, it doesn't care if a front matter title is present and it reports an issue. I'll think about whether that might be correct, but it seems wrong to me right now, so I'm calling this a bug and you can assume I will fix it in the next release. Sorry about that!

kerem commented

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

Author

Owner

@stephanschubert commented on GitHub (Mar 25, 2018):

@DavidAnson Ah I see—thanks for taking the time to fix it 👍

@stephanschubert commented on GitHub (Mar 25, 2018): @DavidAnson Ah I see—thanks for taking the time to fix it 👍

kerem commented

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

Author

Owner

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

Is this released in version 0.12.0? I'm still seeing this issue. I'm using version 0.14.0 of markdownlint-cli, where I believe version 0.12.0 is included.

https://github.com/igorshubovych/markdownlint-cli/releases/tag/v0.14.0

I also have similar format/content as the original post but I'm getting error reporting that H1 heading is missing.

@amimas commented on GitHub (Mar 9, 2019): Is this released in version 0.12.0? I'm still seeing this issue. I'm using version 0.14.0 of markdownlint-cli, where I believe version 0.12.0 is included. https://github.com/igorshubovych/markdownlint-cli/releases/tag/v0.14.0 I also have similar format/content as the original post but I'm getting error reporting that H1 heading is missing.

kerem commented

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

Author

Owner

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

Yes, this fix should be present in recent releases. Can you please show an example of this not working as you expect?

@DavidAnson commented on GitHub (Mar 9, 2019): Yes, this fix should be present in recent releases. Can you please show an example of this not working as you expect?

kerem commented

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

Author

Owner

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

Here's the the snippet of the first few lines of a file that is being flagged:

---
id: create-schema
title: Create Schema
sidebar_label: Create Schema
---

## Pre-requisites

- Ensure that all requirements described in the [Requirements](index.md#requirements) are met
...

And here's my complete .markdownlint.json file:

{
  "default": true,
  "MD002": { "level": 2 },
  "MD003": { "style": "atx" },
  "MD007": { "indent": 4 },
  "MD009": { "number": 0 },
  "MD010": false,
  "MD012": { "maximum": 2 },
  "MD013": false,
  "MD024": { "allow_different_nesting": true },
  "MD035": { "style": "---" }
}

When I run markdownlint-cli, I get an error like this:

../docs/deployment/create-schema.md: 7: MD041/first-line-h1 First line in file should be a top level heading [Context: "## Pre-requisites"]

Also, I realized that not all of my files are being flagged although they all have same frontmatter and similar structure.

@amimas commented on GitHub (Mar 9, 2019): Here's the the snippet of the first few lines of a file that is being flagged: ```markdown --- id: create-schema title: Create Schema sidebar_label: Create Schema --- ## Pre-requisites - Ensure that all requirements described in the [Requirements](index.md#requirements) are met ... ``` And here's my complete `.markdownlint.json` file: ```json { "default": true, "MD002": { "level": 2 }, "MD003": { "style": "atx" }, "MD007": { "indent": 4 }, "MD009": { "number": 0 }, "MD010": false, "MD012": { "maximum": 2 }, "MD013": false, "MD024": { "allow_different_nesting": true }, "MD035": { "style": "---" } } ``` When I run markdownlint-cli, I get an error like this: ``` ../docs/deployment/create-schema.md: 7: MD041/first-line-h1 First line in file should be a top level heading [Context: "## Pre-requisites"] ``` Also, I realized that not all of my files are being flagged although they all have same frontmatter and similar structure.

kerem commented

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

Author

Owner

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

You're not customizing MD041 as you do in #169, so it is enabled with its default behavior of looking for an H1 heading. Unfortunately, the description of the rule is confusing - or maybe the behavior is confusing. MD041 respects the YAML title property and won't warn if an H1 is missing but title is present. BUT if you start the document with a different heading than what it's configured with (default level 1), then it will complain again. Right now, this feels weird to me, so I'll think more about it. But for your purposes, if you configure MD041 as you do in #169, I think you'll get the behavior you want:

"MD041": { "level": 2 }

PS - number is not a valid parameter for MD009.

@DavidAnson commented on GitHub (Mar 9, 2019): You're not customizing `MD041` as you do in #169, so it is enabled with its default behavior of looking for an H1 heading. Unfortunately, the description of the rule is confusing - or maybe the behavior is confusing. `MD041` respects the YAML `title` property and won't warn if an H1 is missing but `title` is present. BUT if you start the document with a different heading than what it's configured with (default `level` 1), then it will complain again. Right now, this feels weird to me, so I'll think more about it. But for your purposes, if you configure `MD041` as you do in #169, I think you'll get the behavior you want: ```json "MD041": { "level": 2 } ``` PS - `number` is not a valid parameter for `MD009`.

kerem commented

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

Author

Owner

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

Okay, I've convinced myself the behavior of MD041 should change. If a YAML title property is present, this rule should accept that as the "top level heading" and not warn again no matter what's in the body of the document. If it behaved that way, your configuration above would do what you want without any changes. If I still feel this way tomorrow, I'll look at making this change. Thanks for calling this out!

@DavidAnson commented on GitHub (Mar 9, 2019): Okay, I've convinced myself the behavior of `MD041` should change. If a YAML `title` property is present, this rule should accept that as the "top level heading" and not warn again no matter what's in the body of the document. If it behaved that way, your configuration above would do what you want without any changes. If I still feel this way tomorrow, I'll look at making this change. Thanks for calling this out!

kerem commented

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

Author

Owner

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

PS - number is not a valid parameter for MD009.

Thanks so much for the note. I'll take a look at the doc again.

@amimas commented on GitHub (Mar 9, 2019): > PS - number is not a valid parameter for MD009. Thanks so much for the note. I'll take a look at the doc again.

kerem referenced this issue

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

[PR #1946] [MERGED] Bump @stylistic/eslint-plugin from 5.7.1 to 5.8.0 #3668