Skip to content

md024.md

Latest commit

 

History

History
87 lines (58 loc) · 2.12 KB

md024.md

File metadata and controls

87 lines (58 loc) · 2.12 KB

MD024 - Multiple headings with the same content

Tags: headings

Aliases: no-duplicate-heading

Parameters:

  • siblings_only: Allow duplicate headings in different parent headings (boolean, default false)
  • allow_different_nesting: Allow duplicate headings at different nesting levels (boolean, default false)

This rule is triggered when multiple headings have the same content:

# Introduction

## Section 1

## Section 1

To fix this, use unique heading text:

# Introduction

## Section Overview

## Section Details

The siblings_only parameter allows duplicate headings in different parent sections:

# Chapter 1
## Introduction
## Setup

# Chapter 2
## Introduction  <!-- Allowed if siblings_only is true -->
## Setup         <!-- Allowed if siblings_only is true -->

But headings with the same parent are still considered violations:

# Chapter 1
## Introduction
## Introduction  <!-- Always a violation -->

The allow_different_nesting parameter allows duplicate headings at different levels:

# Introduction
## Introduction  <!-- Allowed if allow_different_nesting is true -->

But duplicates at the same level are still violations:

# Introduction
# Introduction  <!-- Always a violation -->

When both options are enabled:

  • siblings_only = true AND allow_different_nesting = true: Duplicates are only violations if they have the same parent AND are at the same heading level

Note: Content comparison is case-sensitive and whitespace is normalized (multiple spaces are collapsed to single spaces).

#   Section   1   
##  Section 1      <!-- Violation: normalizes to same content -->

### Section 1
### section 1      <!-- Not a violation: different case -->

Note: Empty headings are treated as having empty content and will trigger violations:

##
##                 <!-- Violation: both are effectively empty -->

Rationale: Duplicate headings can be confusing and may indicate a documentation structure issue. They can also cause problems with automatic link generation and table of contents.