TOC can't link to headings containing dots or brackets

[pmatulis]

The TOC does not work well. For example, the MAAS docs historical release notes page (source file: release-notes-all.md) exhibits the following symptoms:

• The numerical headers do not produce working TOC entries
• Any identical headers do not produce working TOC entries with the exception of the first occurrence

[nottrobin]

Yes, docs and brackets seem to cause a problem. Thanks for pointing that out.This should be fixed.

However with regard to the identical headings issue, I'm not sure this is really a bug.

Firstly, surely "Major new features" should be a level 3 rather than level 2 headings on that page?

More generally, the reason it doesn't work for headings with the same name is because IDs are generated from the headings, and IDs in the HTML spec are supposed to be unique. Personally, I think this is a perfectly good implementation which can then encourage us to create unique headings. I don't really see the use of having a table of contents that contains many items with the same name. They should be given unique names to be easily distinguished.

[pmatulis]

More generally, the reason it doesn't work for headings with the same name is because IDs are generated from the headings, and IDs in the HTML spec are supposed to be unique. Personally, I think this is a perfectly good implementation which can then encourage us to create unique headings. I don't really see the use of having a table of contents that contains many items with the same name. They should be given unique names to be easily distinguished.

Well, evidently we do have docs that have identical headers and for very good reasons (such as the release notes). Is there no way to make it work? If not, what do you suggest? I do realize that the release notes are probably the only document that has this requirement.

[nottrobin]

How are the release notes generated? Are they hand-written? Because in this case if the headings were set to the correct levels, you would have "2.2.0 (beta4)", "2.2.0 (beta3)" etc. as the second-level headings, so they would appear in the TOC, and the third-level headings ("Major new features") wouldn't be in the TOC at all. Of course we still need to fix the dots and brackets problem.

[pmatulis]

They are hand-written. I'll take a look at refactoring it.

[pmatulis]

Only including 2nd-level links in the TOC is very limiting, especially for a page such as the release notes. Yet allowing for 3rd-level links brings us back to the issue of duplicate text headers not becoming links. I feel trapped in a small box. Do you have a suggestion as to how the release notes can be displayed? Users complain of not having a decent TOC for such a document. They want to see quickly what new features have appeared and this can be accomplished, in principle, by a TOC, especially since this is what was available in the old MAAS docs.

[pmatulis]

I filed a separate issue to cover the last comment. See #80.