Problems with anchors with the same name in a page

[huygur]

This might be an edge case, but when a subtitle with the same name appears multiple times on a single page, the anchor links are not correctly assigned.

In my case, there are 2 Limitations subtitles in this page , and I recently added a new one.
There are all in the same level (2nd level title), so at a first glance nothing seems wrong.
But in such cases, the links are generated as follows:

https://docs.camunda.io/docs/components/modeler/web-modeler/play-your-process/#limitations
https://docs.camunda.io/docs/components/modeler/web-modeler/play-your-process/#limitations-1

The issue arises when I add a new title and subtitle (subtitle named "Limitations" again) above the existing ones. In this case, the existing links will be updated as follows:

#limitations --> #limitations-1
#limitations-1 --> #limitations-2

and my new anchor link will be: #limitations

I solved this problem by defining a custom anchor in this docs page, so if I referred these links somewhere, they won't be altered.
But I think we need to pay attention to this somehow.

[huygur]

Not sure if I used the correct label, please correct if it is wrong 😄

[akeller]

@camunda/tech-writers @pepopowitz, I listed this as a bug, but I can see us addressing this in a couple of different ways. Can you please decide on the best path forward for situations like this?

[pepopowitz]

I don't believe we have enough infrastructure or tooling to support the canonicalization/preservation of anchors on pages, nor do I think we should, as I think the effort would far exceed the benefit. To me the contract in terms of preserving a URL for SEO/bookmark purposes does not include anchors. In other words, I don't think we or docusaurus are doing anything wrong by adjusting the anchors of a page when the content itself changes.

My stance on the best path forward is not to worry about this situation. If in the moment a person feels like adjusting in the way described in the body, great...but I don't see it as necessary.