useTopLevelHeading (Markdown)

Language Markdown

Summary

Rule available since: v2.5.8
Diagnostic Category: lint/nursery/useTopLevelHeading
This rule doesn’t have a fix.
The default severity of this rule is information.
Sources:
- Same as first-line-heading

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useTopLevelHeading": "error"
6
      }
7
    }
8
  }
9
}

Description

Require Markdown documents to start with a top-level heading.

Requires the first block in the document to be a level-1 heading, either ATX (# Heading) or setext (Heading followed by ===).

Leading HTML comments used as file preamble are ignored when determining the first block.

The rule does not report when the first block is an HTML block or a thematic break. HTML blocks are permitted because some projects use HTML markup for their heading, especially in READMEs.

Examples

Invalid

1
Some text
2

3
# Heading

code-block.md:1:1 lint/nursery/useTopLevelHeading ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Missing top-level heading.
  
  > 1 │ Some text
      │ ^^^^^^^^^
  > 2 │ 
      │ 
    3 │ # Heading
    4 │ 
  
  ℹ The document should start with a top-level heading (h1) so readers and tools can identify its title. Add a # Heading (or a level-1 setext heading) at the start of the document.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

Valid

1
# Heading
2

3
Some text

1
---
2
title: Example
3
---
4

5
## Section

1
<div>Intro</div>
2

3
## Section