1. Home
  2. Docs
  3. Extensions
  4. 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).

ID generation rules

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

Examples:

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:

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.