Don't include subsections in site-wide table of contents #4065
Conversation
We now use Asciidoc's shorthand for IDs (e.g. `[#some_id_here]`, see https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#ids-roles-and-options) but this isn't being picked up by the script that builds nav.json used to build the site-wide table of contents. This meant that sections of the Pico SDK had incorrect anchors inferred from their titles rather than the Asciidoc source where they would of the form `group_hardware_base`, etc. Fix this by adding a branch to detect shorthand IDs as well as the "anchor" syntax of `[[some_id_here]]`.
To reduce the number of elements included on every single page of the documentation site, no longer include subsections of every section (e.g. terminate at Pico C SDK > Hardware APIs > hardware_adc, rather than also including the subsections of "Detailed Description", "Functions", etc.) as these are available in the right-hand "On this page" TOC shown on wide-enough screens. Note we're not yet cutting down the amount of markup to render the TOC but starting by cutting out the source data. This removes the JavaScript logic to render the currently clicked section in bold.
In development, it comes down from 12,878 elements under |
I was about to reply "That seems like a shame", but then I noticed that the RHS menu does highlight the currently-being-viewed section of the page in bold 👍 E.g. So I just need to train my eyes to look at the RHS menu instead of the LHS menu... 😂 |
|
I thought it was safe to remove as it is a little misleading: it highlights the anchor on the page you clicked but as soon as you scroll, it is no longer accurate. The "On this page" section doesn't have this problem as it live highlights and expands the page structure as you scroll. |
GitHub: #4063
To reduce the number of elements included on every single page of the documentation site, no longer include subsections of every section (e.g. terminate at Pico C SDK > Hardware APIs > hardware_adc, rather than also including the subsections of "Detailed Description", "Functions", etc.) as these are available in the right-hand "On this page" TOC shown on wide-enough screens.
Note we're not yet cutting down the amount of markup to render the TOC but starting by cutting out the source data.
This removes the JavaScript logic to render the currently clicked section in bold.