I use shortcodes to create some content headings. The shortcode translates, for example, to <h2 id="headingId">Heading Text</h2>. The headings are added correctly, but I found that they are not included in the page TOC (“mini TOC”), which is created using TableOfContents.
When using the exact same HTML heading code directly in the MD file, the heading is included in the mini TOC.
This is a major issue for me as I have planned to rely heavily on using heading shortcodes.
Then you need to replan. This is not supported.
Could this potentially be supported in the future?
Using heading shortcode not only simplifies adding the headings (which can also be partially achieved with archetypes); it reduces errors and ensures consistency, and perhaps most importantly — it allows changing the heading style and/or text in one place.
Can I, theoretically, write a template partial that based on a front-matter variable might, instead of using TableOfContents, manully create a similar TOC (using the same CSS styles), for example by using JS code that searches the file for heading shortcodes based on a predefined heading-shortcode naming logic?
For now, I implemented a partial workaround: I added a custom mini-TOC implementation for shortcode headings, based on custom site-parameters configuration. I don’t have time to write a complete solution that parses the source file and handles both standard MD or HTML headings and shortcode headings (or generates the source files for Hugo); in the temp solution you can only select to create a TOC for standard headings or for shortcode headings (but not both), or not to display the TOC at all. Of course, you can always decide not to use the shortcode in a specific instance and add the heading directly using MD.
The custom mini TOC uses the same CSS as the Hugo TOC, so it looks the same, but there is one functional difference — the current browsing location is not highlighted in the custom TOC.
What do your shortcodes offer that the default markdown doesn’t? The markdown already creates an id on each header.
it reduces errors and ensures consistency, and perhaps most importantly — it allows changing the heading style and/or text in one place.
I’m curious what errors and inconsistencies you’re coming across. With styling, shouldn’t that be in the site CSS? Or couldn’t you use a generic styling shortcode and apply it to the heading instead?
I’ll give you an example: I want to document functions, for example, in a similar manner, with headings such as “Request Parameters”, “Response Parameters”, “Examples” (and more). I also need other heading types, for example for release notes. I want all these headings to use the same text and IDs, and be styled in a similar manner. Not only do shortcodes make it simpler to add such headings and ensure consistency across all our docs, but if tomorrow I decide to rephrase any of the headings’ text or change the heading level, for example, I only need to make the changes in one place and they will automatically be applied to all uses of the shortcode, instead of doing search-and-replace across all our docs (which not only consumes more time, even if we automate it with a script — which we’ll need to write … — but is also more error prone).
BTW, the less heading levels we include in the mini TOC, the less of an issue this becomes. We currently include h2 and h3 levels, but I might change this. Most examples that I saw include only h2 headings. We were able to implement a collapsible on-page alternative mini-TOC view for small screens, so my vision (when we have the time …) is to always have a collapsible TOC of all heading levels at the start of the page, and have a constant h2-only mini TOC on the right side of the page (on bigger screens).
It turns out that the inconsistent behavior is probably related to a feature that’s implemented in our JS code (which I didn’t write). it’s possible that the code currently applies this feature specifically to uses of the TableOfContents template, in which case we should be able to easily apply it also to my workaround TOC. The developer who wrote the code will look into this when he returns from vacation.