[SLING-10686] Site: Fix TOC links

• Type: Improvement
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Component/s: Site
• Assignee: Unassigned
• Reporter: Konrad Windszus
• Created: 29/Jul/21 08:48
• Updated: 29/Jul/21 09:03

Description

Currently the table of contents is generated by https://github.com/apache/sling-site/blob/ac12de1fa98bd50958d6d0e606e7cc35f05f99aa/src/main/jbake/templates/toc-brick.tpl with the help of the https://github.com/nghuuphuoc/tocjs (which is no longer maintained).
It generates anchor links with a `-1` suffix like `https://sling.apache.org/documentation/bundles/scripting/scripting-htl.html#type-conversions-1` which don't work when called outside the page.

To fix this we should either
1. switch to the markdown TOC macro (as outlined in https://github.com/vsch/flexmark-java/wiki/Table-of-Contents-Extension). This requires adjustments though of the TOC macro in almost every MD source as this by default only renders entries for h2-h3.
2. generate the TOC in the template with another JS library
3. generate the TOC in the template purely server-side (requires parsing of HTML and probably a lot of groovy code)