Markdown shortcode content is not included in Table of Contents (TOC)

[JeppeKlitgaard]

What version of Hugo are you using (hugo version)?

hugo v0.111.3+extended linux/amd64 BuildDate=unknown

Does this issue reproduce with the latest release?

Yes

---

I am still running into the issue described in #6690, which was closed due to doubts whether it was a bug or bad configuration. I believe it is a bug, as I can reproduce the issue described there, and so could the lowRISC team in lowRISC/opentitan#3313.

The way I am reading the documentation, a markdown shortcode ({{% md-shortcode %}}) should be fully rendered and therefore be a part of the generated table of contents – https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown

In Hugo 0.55 we changed how the % delimiter works. Shortcodes using the % as the outer-most delimiter will now be fully rendered when sent to the content renderer. They can be part of the generated table of contents, footnotes, etc.

Alternatively I believe this could be read as the included markdown being rendered as HTML and therefore would be present as HTML in the TOC heading lists, etc, but any headings included would not be considered for the TOC. If this is the case, this should perhaps be a proposal instead of a bug report.

I think there is a bit of well-meaning misdirection going on in the forum when searching for similar issues: https://discourse.gohugo.io/t/no-table-of-contents-from-partial-calling-separate-markdown-files/38967. I don't believe the proposed solution works.

I can't get this to work, however, nor could @jcyrss. See also: https://discourse.gohugo.io/t/sections-wrapped-in-a-shortcode-do-not-appear-in-the-toc/21304/11

My shortcode includes another markdown file and looks like:

{{- $filename := printf "%s.generated.md" (.Get 0) -}}
{{- (.Page.Resources.GetMatch $filename).Content | safeHTML -}}

But the included headings are not included in the TOC.

I am keen to elaborate on any points that aren't clear. The issue should be easy to reproduce on any Hugo installation:

1. Add the shortcode below (name it includer.html)
2. Create a file with a few markdown headings and name it include_me.md
3. Include it on a page with {{% includer "include_me.md" %}}
4. Observe that included markdown is not part of the TOC

{{- (.Page.Resources.GetMatch (.Get 0)).Content | safeHTML -}}

[jmooring]

@JeppeKlitgaard There are some scenarios where it not possible for the .TableOfContents method to capture headings. See https://discourse.gohugo.io/t/shortcodes-within-shortcodes-not-rendering/42343 for an example.

You have two options:

1. Build your own TOC partial that parses the rendered page content (example)
2. Use something like tocbot

[JeppeKlitgaard]

@jmooring Thank you for your quick and informative reply!

I will leave this open for now, as I still think this could be considered either a bug or alternatively be turned into an enhancement proposal, albeit the technical details of that are beyond my knowledge of Hugo.

I will have a go at implementing your first suggestion on my site. Thank you!

[bep]

To be clear,

Using the {{<% delimiter as the outermost delimiter in a Markdown file will make that rendered shortcode part of the Markdown document, and any CommonMark heading in the rendered shortcode output will be included in the ToC.

If you're saying that the above isn't true, that's a bug.

What I suspect, though, is that what gets included in {{% includer "include_me.md" %}} doesn't contain CommonMark headings (maybe wrapped in a div?)

I agree that there are situations where it would be useful to calculate the ToC based on the rendered output, but there's a chicken-and-egg problem with that, and I suspect we would want to wait for the planned new defer keyword to tackle that.

[JeppeKlitgaard]

Thank you for getting back to me!

If you're saying that the above isn't true, that's a bug.

A sample of a markdown file I am including using the includer shortcode:

## Background

As part of my undergraduate studies I recently had to write a formal report on the exciting
topic of mechanical resonance after having collected data from the transient and
steady state responses of a oscillating torsional pendulum.

...

These aren't pre-rendered into HTML or wrapped in any HTML elements.

With a number of other headings further down the document, but these are not included in the ToC.

From the other discussions I have linked, I believe other people are having a similar issue.

[bep]

OK, I see it now:

See the passing test case at https://github.com/gohugoio/hugo/pull/10867/files

• Calling .Content on a Markdown Page, will always render it (to HTML, presumably)
• If you include HTML into a Markdown file, that is not CommonMark (as my comment above)
• If you instead use .RawContent, it should work much better (RawContent is the raw Markdown excluding any front matter).
• Also, note that you don't need to use safeHTML (not that it matters too much).

[JeppeKlitgaard]

Changing to .RawContent does the trick – thank you so much for such a swift reply! I hope this will help out other people as well. It might be helpful to include a quick comment about RawContent vs Content on the documentation page: https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown

Feel free to close this and thank you again

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.