useSingleTopLevelHeading (Markdown)

Language Markdown

Summary

Rule available since: v2.5.12
Diagnostic Category: lint/nursery/useSingleTopLevelHeading
This rule doesn’t have a fix.
The default severity of this rule is information.
Sources:
- Inspired from single-title

How to configure

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

Description

Enforce that a Markdown document has a single top-level heading.

A Markdown document should have a single top-level heading that acts as the document’s title. By default, level 1. Subsequent headings should use lower levels (h2, h3, etc).

The rule reports a document only when it follows this convention, so it stays silent when:

the document starts with a front matter block (only parsed when markdown.parser.frontmatter is enabled): the front matter may already carry the document title, so a heading in the body isn’t necessarily a duplicate;
the heading isn’t a direct child of the document: a heading nested in a blockquote or in a list item never counts as the title, and is never reported as an extra top-level heading;
the first heading at the configured level isn’t the document’s title, because it is preceded by something other than blank lines and HTML comments, such as a heading at another level or a paragraph.

Examples

Invalid

1
Title
2
=====
3

4
Another top-level heading
5
=========================

code-block.md:4:1 lint/nursery/useSingleTopLevelHeading ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ This document has more than one top-level heading.
  
    2 │ =====
    3 │ 
  > 4 │ Another top-level heading
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^
  > 5 │ =========================
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^
    6 │ 
  
  ℹ The other top-level heading is here.
  
  > 1 │ Title
      │ ^^^^^
  > 2 │ =====
      │ ^^^^^
    3 │ 
    4 │ Another top-level heading
  
  ℹ A single top-level heading acts as the document's title. Additional ones break document outlines, tables of contents, and the structure produced when converting to HTML.
  
  ℹ Demote this heading to a lower level, or move its section into its own 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
Title
2
=====
3

4
## Heading
5

6
## Another heading

1
# Title
2

3
> # Quoted heading

Options

`level`

Use the level option to change which heading level is treated as the top-level one. This is useful when an external tool (a static site generator, for example) already injects an h1 for the page title, so the Markdown source is expected to start at h2. The value must be between 1 and 6.

Default: 1.

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useSingleTopLevelHeading": {
6
          "level": "on",
7
          "options": {
8
            "level": 2
9
          }
10
        }
11
      }
12
    }
13
  }
14
}

1
## Section
2

3
## Another top-level section

code-block.md:3:1 lint/nursery/useSingleTopLevelHeading ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ This document has more than one top-level heading.
  
    1 │ ## Section
    2 │ 
  > 3 │ ## Another top-level section
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    4 │ 
  
  ℹ The other top-level heading is here.
  
  > 1 │ ## Section
      │ ^^^^^^^^^^
    2 │ 
    3 │ ## Another top-level section
  
  ℹ A single top-level heading acts as the document's title. Additional ones break document outlines, tables of contents, and the structure produced when converting to HTML.
  
  ℹ Demote this heading to a lower level, or move its section into its own 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.