markdown_no_duplicate_headings

Reject a later Markdown heading whose generated base anchor collides with an earlier heading.

Anchors lowercase Unicode text, turn whitespace into -, and remove ASCII punctuation except - and _; explicit {#id} heading attributes use that id. The finding cites the first colliding heading. This catches case and punctuation variants that render as competing deep-link anchors while allowing repeated visible labels with deliberately distinct explicit ids.

Options

This rule takes no kind-specific options.

Plus the common paths, level, id, when, scope_filter, and expect_matches fields. This table is generated from the JSON Schema; option types and defaults are authoritative.

Example

Headings that normalize to the same anchor are reported

The rule fires on this repository:

• README.md✗

  ✗ error unique-headings

  5:1 Markdown heading generates duplicate anchor `#api-http` related: first heading with this anchor: README.md:3:1-4:1

README.md

# Project

## API: HTTP

## API HTTP

With this .alint.yml:

version: 1
rules:
  - id: unique-headings
    kind: markdown_no_duplicate_headings
    paths: "**/*.md"
    level: error

alint check reports:

--- README.md ------------------------------------------------------------------
  x  error    unique-headings
              5:1  Markdown heading generates duplicate anchor `#api-http`
              related: first heading with this anchor: README.md:3:1-4:1

Summary (1 violation):
  x 1 error
  0 passing * 1 failing

Repeated labels with distinct explicit anchors remain valid

This repository is compliant:

• README.md✓

README.md

# Project

## Examples {#basic-examples}

## Examples {#advanced-examples}

With this .alint.yml:

version: 1
rules:
  - id: unique-headings
    kind: markdown_no_duplicate_headings
    paths: "**/*.md"
    level: error

alint check reports:

v All 1 rule(s) passed.