markdownlint "MD041/first-line-heading" in CI

By Daniel Zoghalchali·Latchkey

markdownlint rule MD041 requires the first line of a file to be a top-level heading (H1). It fires when a file opens with front matter, a badge, an image, or an H2, and exits non-zero.

What this error means

markdownlint reports "MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading" on the first content line of a doc.

docs/index.md:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "## Overview"]

Common causes

The file opens with non-heading content

A badge row, an image, or a paragraph precedes the first heading, so line 1 is not an H1.

YAML front matter is not recognized as such

A docs-site page starts with --- front matter; if markdownlint is not told to skip it, the first real line is not an H1.

How to fix it

Start the file with an H1

Add a top-level # heading as the first content line, or move badges below it.

# Project Name

[![build](badge.svg)](link)

Intro paragraph...

Configure MD041 to accept front matter or a different level

1. If pages use front matter, ensure markdownlint parses it (front matter is skipped by default).
2. To allow an H2 start, set level in MD041.
3. Or disable MD041 for generated index files.

{
  "MD041": { "level": 1, "front_matter_title": "^\\s*title\\s*[:=]" }
}

How to prevent it

• Open every doc with a single H1 as the first content line.
• Configure front_matter_title so titled front matter satisfies MD041.
• Exempt auto-generated index pages if they cannot start with an H1.

Frequently asked questions

Related guides

References

• GitHub Actions documentation