0 Fork 0

Files

T

dualfrozandAlexandre Mutel 9006f0b4a2 Fix heading auto-link hijacking nested link labels (#668 ) (#949 )

* Fix heading auto-link hijacking nested link labels (#668)

* Refactor heading reference resolution to init-only state (#949)

---------

Co-authored-by: Alexandre Mutel <alexandre_mutel@live.com>

2026-09-19 11:41:48 +02:00

2.4 KiB

Raw Permalink Blame History

title

title
Auto-identifiers

Auto-identifiers

Enable with .UseAutoIdentifiers() (included in UseAdvancedExtensions()).

This extension automatically generates id attributes for all headings, similar to Pandoc auto identifiers. This is essential for linking to specific sections.

How it works

Every heading gets an id attribute derived from its text content:

## Getting Started

Renders as:

<h2 id="getting-started">Getting Started</h2>

You can then link to it:

See [Getting Started](#getting-started).

With the default AutoLink option, [Getting Started] also links to the heading. These implicit heading references do not resolve inside another still-open link or image bracket. For example, [Read [Getting Started]](/guide) links the entire label Read [Getting Started] to /guide. Explicit reference definitions such as [Getting Started]: /guide retain normal CommonMark reference-link behavior.

ID generation rules

Convert to lowercase
Remove anything that is not a letter, number, space, or hyphen
Replace spaces with hyphens
Remove leading/trailing hyphens

Examples:

{.table}

Heading	Generated ID
`# Hello World`	`hello-world`
`## C# Tips & Tricks`	`c-tips--tricks`
`### 2. Installation`	`2-installation`

Duplicate handling

If two headings produce the same ID, a numeric suffix is appended:

## Section
## Section
## Section

Produces: section, section-1, section-2.

Options

UseAutoIdentifiers accepts an AutoIdentifierOptions flags enum:

using Markdig.Extensions.AutoIdentifiers;

var pipeline = new MarkdownPipelineBuilder()
    .UseAutoIdentifiers(AutoIdentifierOptions.GitHub)
    .Build();

Available options:

{.table}

Option	Description
`AutoIdentifierOptions.Default`	Standard auto-identifier behavior
`AutoIdentifierOptions.GitHub`	GitHub-compatible ID generation
`AutoIdentifierOptions.AutoLink`	Also create a self-link anchor
`AutoIdentifierOptions.AllowOnlyAscii`	Strip non-ASCII characters from IDs

Combining with generic attributes

You can override the auto-generated ID using Generic attributes:

## My Heading {#custom-id}

The explicit #custom-id takes precedence over the auto-generated one.

2.4 KiB Raw Permalink Blame History