dualfrozandAlexandre Mutel
9006f0b4a2
* 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>
96 lines
2.4 KiB
Markdown
96 lines
2.4 KiB
Markdown
---
|
|
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](https://pandoc.org/MANUAL.html#extension-auto_identifiers). This is essential for linking to specific sections.
|
|
|
|
## How it works
|
|
|
|
Every heading gets an `id` attribute derived from its text content:
|
|
|
|
```markdown
|
|
## Getting Started
|
|
```
|
|
|
|
Renders as:
|
|
|
|
```html
|
|
<h2 id="getting-started">Getting Started</h2>
|
|
```
|
|
|
|
You can then link to it:
|
|
|
|
```markdown
|
|
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
|
|
|
|
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:**
|
|
|
|
{.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:
|
|
|
|
```markdown
|
|
## Section
|
|
## Section
|
|
## Section
|
|
```
|
|
|
|
Produces: `section`, `section-1`, `section-2`.
|
|
|
|
## Options
|
|
|
|
`UseAutoIdentifiers` accepts an `AutoIdentifierOptions` flags enum:
|
|
|
|
```csharp
|
|
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](generic-attributes.md):
|
|
|
|
```markdown
|
|
## My Heading {#custom-id}
|
|
```
|
|
|
|
The explicit `#custom-id` takes precedence over the auto-generated one.
|