Duplicate heading anchors

[reakaleek]

Describe the bug

If there are multiple headings with the same title e.g.

## Heading 1
### Example
## Heading 2
### Example

Then the table of contents navigation gets confused because there are multiple sections with the same id.

Expected behavior

Each heading should have a unique anchor

Steps to reproduce

No response

Tooling

• docs-builder
• migration tooling
• I'm not sure

[Mpdreamz]

Should this be an error?

[KOTungseth]

We should be using unique titles and anchors for each of our Docs pages.

We should error on this in the Docs build.

[bmorelli25]

Should this be an error?

Requires a hint phase so folks can clean up content before we start to warn.

[theletterf]

I think it is not always possible to have unique anchors for headings: in some cases, certain strings are correct in the context of reference documentation (for example, "Examples").

Here is my pragmatic suggestion:

• Automatically generate anchor links through a utility class in case identical headings are detected (including dropdown headings). This ensures ToC works now and will never fail.
• Add warnings hints for duplicated H2 headings (where we don't expect this to happen)

[vishaangelova]

In some Beats reference docs, there’s a need for a fix regarding these duplicate headings.

For example, in the Azure Blob Storage Input doc, some configuration attributes are listed with an example configuration, which is provided under a separate heading (### Example configuration). Currently, only the first such heading is displayed in the right-side navigation + other instances of the same heading link to the section where the first heading was used.

Could we generate unique anchors for duplicate headings (e.g. [#heading], [#heading-1], [heading-2], etc.)?

We’d also need to allow for the addition/removal of further headings with the same heading title, while also keeping the links to existing headings intact - or at least, keep them working.

[reakaleek]

Generating unique anchors with an index is not trivial. The markdown is our source of truth.

This means if someone adds a duplicate heading in the middle of the documentation the indexes will shift. We don't have a way to persist the anchor for a specific heading

[reakaleek]

One solution I can think of is:

Error on duplicate anchors instead of headings. And make it clear in the error message that if you have duplicate headings/anchors, you can specify custom anchors to fix it.

[theletterf]

@reakaleek Could we run an assembled test to check how many duplicated anchors we have across the entire docs?

[reakaleek]

@reakaleek Could we run an assembled test to check how many duplicated anchors we have across the entire docs?

I will try to get the numbers

[reakaleek]

@reakaleek Could we run an assembled test to check how many duplicated anchors we have across the entire docs?

I will try to get the numbers

For some reason, I'm unable to run a docs-assembler build. I will try it again tomorrow.