Any way to set custom heading ID?

[Vija02]

Right now the ID for heading is automatically generated from the text. Is there a way to set a custom ID?
I tried

## My Heading {#custom-id}

but that doesn't seem to work.

[fabriciomurta]

No.

Well, the is the short answer for that, you probably expected that,right?

So, now for a long answer:

ID handling in headings is there and it has some mechanisms to ensure it works in most (if not all) scenarios. We have gone as far as ensuring no conflicts happen when the heading has the same words (by appending -1, -2, and so on), so at least you shouldn't have actual conflicts, but to get the actual ID, in case you have several sub-headings with the same name, the best way would be to build and check how it was generated.

Of course there will be issues in case, say, you add a topic between two conflicting ones. If you previously linked the "second" topic elsewhere, the link would then point to the "new second" one, so -- yes -- that's might be a good feature for Retype. I don't remember anyone else raising the subject so far; feel free to log an issue to request the feature if you really miss that. Explaining why you miss it (scenarios where this can be used) would also help not only support from other members in the community -- but help us ensure it will work for you in the event it is developed by checking out scenarios we might not have foreseen.

Maybe this hasn't been raised this far as (I am assuming) documentation can be split in pages for easier reading and this would reduce the chances of conflicting topics in a same page.

By the way, where have you based the syntax you tried from?

[Vija02]

The syntax is from here: https://www.markdownguide.org/extended-syntax/#heading-ids

My use case is just precaution for the future in case the title changes. That'll result in the id changing which will break links to it. I guess the core issue is my fear of broken links.

If you can set an ID to it, it'll persist through text changes. And it'll be more obvious during deletion that a heading is being linked when you can see that it has a custom id attached to it.

[geoffreymcgill]

## My Heading {#custom-id}

Very good suggestion. Currently, Retype does not support this syntax, although theoretically we can build support into a future release.

I will log this as a feature request and we will do our best to implement. I can't say when this will be implemented, but it would be a very handy feature to have and theoretically it should not require too much development time to get it working.

[geoffreymcgill]

I have this working. We might be able to include in the upcoming Retype v2.0.

If a custom anchor id was provided, the developer/author would be responsible to ensuring it was unique as Retype would not parse and ensure uniqueness as part of its link resolution reporting (which have also been significantly improved in v2.0).

Given the following sample:

## Beta {#beta}

Test paragraph.

## Beta {#beta}

Test paragraph.

## Beta

Test paragraph.

## Beta

Test paragraph.

The following anchors would be created:

#beta
#beta
#beta
#beta-1

The last two are managed by Retype which ensures uniqueness.

[Vija02]

That sounds awesome, thanks! 😄

[geoffreymcgill]

Setting a custom anchor id is now supported with Retype v2.0.0-preview.

## My Heading {#custom-id}

The final official v2.0.0 release should be early next week.

Hope this helps.

[geoffreymcgill]

The Generic Attribute syntax and full docs are available in the Markdig documentation, see

https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/GenericAttributesSpecs.md