eslint-plugin-markdown-preferences

Appearance

markdown-preferences/level1-heading-style ​

enforce consistent style for level 1 headings

  • ⚙️ This rule is included in plugin.configs.standard.
  • 🔧 The --fix option on the command line can automatically fix some of the problems reported by this rule.

📖 Rule Details ​

This rule enforces consistent style for level 1 headings in Markdown files. Level 1 headings can be written in two formats:

  1. ATX style: Lines that start with a single # character, followed by a space and the heading text
  2. Setext style: Text followed by a line of = characters (underline)

Both formats are valid according to the CommonMark specification, but mixing styles within a document or project can reduce readability and consistency.

md
<!-- ATX style -->
# This is a level 1 heading

<!-- Setext style -->
This is a level 1 heading
=========================

This rule allows you to enforce either ATX style ("atx") or Setext style ("setext") for all level 1 headings in your Markdown files.

Why enforce this?

  • Consistency: Ensures all level 1 headings follow the same style throughout your documentation
  • Readability: Makes it easier to scan and understand document structure
  • Tooling: Simplifies automated processing and formatting of Markdown files
  • Maintainability: Reduces cognitive load when editing and reviewing documentation

Examples ​

ATX Style ​

md
<!-- eslint markdown-preferences/level1-heading-style: ['error', { style: 'atx' }] -->

<!-- ✓ GOOD -->

# Introduction

# Getting Started

# Configuration

<!-- ✗ BAD -->


Introduction

============


Getting Started

===============


Configuration

=============

Setext Style ​

md
<!-- eslint markdown-preferences/level1-heading-style: ['error', { style: 'setext' }] -->

<!-- ✓ GOOD -->

Introduction
============

Getting Started
===============

Configuration
=============

<!-- ✗ BAD -->


# Introduction



# Getting Started



# Configuration

🔧 Options ​

json
{
  "markdown-preferences/level1-heading-style": [
    "error",
    {
      "style": "atx", // or "setext"
      "allowMultilineSetext": false
    }
  ]
}

style ​

  • Type: "atx" | "setext"
  • Default: "atx"

Specifies which heading style to enforce for level 1 headings:

  • "atx": Enforce ATX style (# Heading)
  • "setext": Enforce Setext style (Heading\n======)

allowMultilineSetext ​

  • Type: boolean
  • Default: false

This option only takes effect when style is set to "atx".

When true, allows Setext headings that span multiple lines. When false, multiline Setext headings are reported as errors.

Note: Multiline Setext headings cannot be automatically fixed to ATX style due to the complexity of handling line breaks in heading text.

📚 Further Reading ​

🚀 Version ​

This rule was introduced in eslint-plugin-markdown-preferences v0.18.0

🔍 Implementation ​