Markdown read with the Docsy theme's readfile shortcode is not included in TOC

Hey all,

I am using the Docsy theme and the readfile shortcode to include markdown files on other pages. I noticed that the right-hand nav is not showing any of the headings that are part of the file that I am including. It only shows headers for content that was already on the page.

I saw that this issue was reported in the past, but could not find a solution to this issue. Is there a way to get the nav populated?

Thank you so much and best regards,

You can call a shortcode two ways:

  1. {{< foo a="b" >}}
  2. {{% foo a="b" %}}

With the {{% %}} notation, the shortcode expects to receive markdown, and fully renders the shortcode before the rest of the page is rendered. So if the markdown received contains headings, those headings will be included in the TOC.

But the Docsy readfile shortcode does this:

{{- $.Scratch.Get "filepath" | os.ReadFile | .Page.RenderString | safeHTML -}}

The markdown is passed through .Page.RenderString, rendering it to HTML, then it is rendered to HTML again due to the {{% %}} notation. So the headings will not be included in the TOC because they were already rendered to HTML.

The underlying problem is that the shortcode has no way of knowing which notation was used when it was called.

I recommend:

  1. Create your own version of the shortcode, to be called only with the {{% %}} notation, AND

  2. Replace this:

    {{- $.Scratch.Get "filepath" | os.ReadFile | .Page.RenderString | safeHTML -}}

    with this:

    {{- $.Scratch.Get "filepath" | os.ReadFile -}}

This is a known issue with the Docsy theme:

Hey @jmooring,

thank you so much for your help and all the support I got from you. This solution works like a charm and was exactly what I was looking for!! :slight_smile:

Best regards,

sorry I just noticed one thing. I was using other shortcodes (conditional-text) in the markdown file that I am including with the readfile shortcode. these shortcodes are not rendering anymore with the new approach. is there a way that I can make them render as well?

Within the markdown file you are reading, which notation is used to call the condition-text shortcode?

I was using % as well.

so basically

## Heading

This is the file for the readfile shortcode

{{% conditional-text include-if="a" %}} This is the conditional text {{% /conditional-text %}}

{{% readfile "/reuse/" %}}

The output then looks like this:


This is the file for the readfile shortcode

{{% conditional-text include-if="a" %}} This is the conditional text {{% /conditional-text %}}

Actually, it doesn’t matter which notation is used to call the condition-text shortcode from within the markdown file you are reading.

This is the same issue:

There are a couple of ways around this:

  1. Generate the TOC with JavaScript as suggested here.
  2. Generate the TOC with a partial as suggested here.
1 Like

For a JS approach, I just tried this:

Works great. Vanilla JS—jQuery not required.

Don’t use their CSS file; roll your own.

Thank you so much. I tried out the TOC partial approach and I can now render the page and see a right-hand nav. But I cannot get the individual nav entries to be listed underneath. It currently looks like this


It should actually list the items as 2 H2s:

  • Default Prometheus server configuration
  • Retention period for metrics

I added the css code from here hugo-testing/toc.html at hugo-forum-topic-42343 · jmooring/hugo-testing · GitHub but I can’t figure out what I need to add to bring each entry onto its own line.

When I build the test site:

git clone --single-branch -b hugo-forum-topic-42343 hugo-forum-topic-42343
cd hugo-forum-topic-42343
hugo server

I see this:

Maybe you have some conflicting CSS with Bootstrap or another library.

Hey @jmooring

it took me a while to find the CSS that was overriding it, but I finally found it and now everything is on its own line. Yay!! :slight_smile:

Thank you so much for your help with this.
Best regards,

1 Like

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.