Add support for custom heading anchors in Markdown.

[Mpdreamz]

Custom heading anchors allow more control over anchor names in generated HTML. Inline annotations can now define specific anchors, and normalization ensures consistent formatting. Updated relevant tests, documentation, and rendering logic to support this feature.

You can now override the autogenerated anchors for headings with

## My header [my-completely-different-anchor]

Updated the syntax guide to document this new feature.

This also addresses the bugs reported in #125

[reakaleek]

What do you think about using curly braces instead of square brackets?

I think curly braces are less likely to be part of a heading.

Kramdown has a similar approach.

They use this:

Hello        {#id}
-----

# Hello      {#id}

# Hello #    {#id}

Source: https://kramdown.gettalong.org/syntax.html#specifying-a-header-id

IMO, Kramdown also cleverly utilizes the #, which makes it even less likely to be part of the heading.

TL;DR

I would suggest either

I prefer this because it seems to be an existing convention across other markdown flavours

# Heading {#id} 

or

# Heading [#id]

[Mpdreamz]

I personally prefer [ ] since it's the syntax for links and will highlight quite nicely in editors.

It will also be easier to disambiguate variable substitutions and these anchors.

A more technical reason I'm not thrilled about brackets is that markdig has an extension to attach arbitrary data to elements using brackets at the end.

We don't use that today but we might in the future. Want to leave that door open

[reakaleek]

Understood.

What do you think about the # as in [#id].

Semantically, this also resembles an URL fragment, making it clearer that this will be the ID of the element.

I understand that it's not very likely. But there is still a possibility that someone wants to create a header like:

# Heading [Part of the heading]

And the the [#id] syntax would lower the chance of conflicts.

[Mpdreamz]

What do you think about the # as in [#id].

Technically that is supported today, we can make it

• A suggestion. We document the feature as [#anchor] but continue to accept [anchor] too.
• A warning. We'll accept [anchor] but warn to use [#anchor] instead.
• An error.

I'm leaning to making this a suggestion then, what do you tink @reakaleek ?

[Mpdreamz]

I've updated the docs to use [#anchor]

[reakaleek]

SGTM. Thank you