Shortcodes within shortcodes not rendering

support
2

No.

The built-in table of contents (.TableOfContents) will not include headings from nested shortcodes, so we will build our own.

Take this for a spin.

The test page includes some content with headings, and calls the snippet shortcode. The snippet includes some content with headings, and calls the note shortcode.

git clone --single-branch -b hugo-forum-topic-42343 https://github.com/jmooring/hugo-testing hugo-forum-topic-42343
cd hugo-forum-topic-42343
hugo server

Files of interest:

  • layouts/_default/single.html
  • layouts/partials/toc.html (contains documentation in header)
  • assets/scss/_toc.scss

By generating the table of contents after Hugo renders the content, we can:

  • Have complete control over HTML structure and attributes (#8338)
  • Modify the heading id attribute in a heading render hook (#8383)
  • Control the start and end levels at the page level and/or site level (#9329)
  • Include raw HTML heading elements in our markdown
  • Generate HTML heading elements from shortcodes invoked with the {{< >}} notation
  • Detect heading elements without id attributes (warning)
  • Detect duplicate heading id attributes (error)
  • Avoid other known issues such as #4735, #6081, #7128, and #7158

Let me know if you run into any problems with the toc partial. I have tested it quite a bit, but I am sure there’s room for improvement.

On a large site, with TOCs on every page, this will have an impact on performance. I have no idea how much. I’ll run some tests in the next couple of days.

Finally, in your note shortcode, do not use a heading element for the title. The TOC will pick that up if your end level is low enough.