# Can Hugo include shortcode headings in TOC?

**URL:** <https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940>\
**Category:** support\
**Created:** [October 14, 2024, 7:59am UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940 "2024-10-14T07:59:41Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![karis](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/karis/32/22946_2.png) [@karis](https://discourse.gohugo.io/u/karis)\
**Post date:** [October 14, 2024, 7:59am UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/1 "2024-10-14T07:59:41Z")

</div>

I have a shortcode that generates data from a JSON file. It has headings in the data and I even added a custom ID. Is there a way to make Hugo pick up these headings for the TOC?

---

<div class="post-metadata">

**Author:** ![karis](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/karis/32/22946_2.png) [@karis](https://discourse.gohugo.io/u/karis)\
**Post date:** [October 14, 2024, 8:38am UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/2 "2024-10-14T08:38:50Z")

</div>

It’s amazing the resources one can find by searching the forum. So I found this article. Method 3 throws an error about define and method 4 returns nil.

> **[Tables of content](https://www.veriphor.com/articles/tables-of-content/#method-4-parse-content)**
>
> Learn how to insert a table of contents into pages on your Hugo site using one of four methods.

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [October 14, 2024, 8:46am UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/3 "2024-10-14T08:46:54Z")

</div>

> [@karis](#):
>
> Is there a way to make Hugo pick up these headings for the TOC?

- Yes, but you need to use (and … understand the) `{{%` shortcode delimiter.
- Also see [RenderShortcodes | Hugo](https://gohugo.io/methods/page/rendershortcodes/) – which can be very powerful, but you need to wrap your head around it and understand what it’s use case is (including markdown).

---

<div class="post-metadata">

**Author:** ![karis](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/karis/32/22946_2.png) [@karis](https://discourse.gohugo.io/u/karis)\
**Post date:** [October 14, 2024, 2:19pm UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/4 "2024-10-14T14:19:08Z")

</div>

> [@bep](#):
>
> Yes, but you need to use (and … understand the) `{{%` shortcode delimiter.

That one returns the code as html unprocessed. My code is creating content from a data file (tables, paragraphs, headings, etc), so only `{{<` works.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [October 14, 2024, 5:13pm UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/5 "2024-10-14T17:13:21Z")

</div>

> [@karis](#):
>
> Is there a way to make Hugo pick up these headings for the TOC?

Does your shortcode produce Markdown or HTML?

> [@karis](#):
>
> So I found this article. Method 3 throws an error about define and method 4 returns nil.

I am the author of that article. I just tested all four methods again with v0.135.0. They all work great.

---

<div class="post-metadata">

**Author:** ![karis](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/karis/32/22946_2.png) [@karis](https://discourse.gohugo.io/u/karis)\
**Post date:** [October 14, 2024, 5:45pm UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/6 "2024-10-14T17:45:27Z")

</div>

> [@jmooring](#):
>
> Does your shortcode produce Markdown or HTML?

It produces HTML.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [October 14, 2024, 5:55pm UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/7 "2024-10-14T17:55:04Z")

</div>

That’s not going to work. If you want to use Hugo’s built-in `TableOfContents` method, your shortcode needs to be something like this:

```plaintext
## Level 2 Markdown heading in shortcode

## Level 3 Markdown heading in shortcode

```

And you need to call it like this:

```plaintext
{{% markdown-headings %}}

```

The shortcode needs to follow the CommonMark specification regarding indentation and mixing HTML with Markdown (i.e., [HTML Blocks](https://spec.commonmark.org/0.31.2/#html-blocks)).

I’ve written about this before, but you might consider using [tocbot.js](https://tscanlin.github.io/tocbot/) to render the TOC on the client side. It has none of the limitations described in this [comparison table](https://www.veriphor.com/articles/tables-of-content/#feature-comparison), and also includes HTML heading elements that appear outside of content (e.g., in a template file such as list.html).

---

<div class="post-metadata">

**Author:** ![karis](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/karis/32/22946_2.png) [@karis](https://discourse.gohugo.io/u/karis)\
**Post date:** [October 15, 2024, 6:16am UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/8 "2024-10-15T06:16:04Z")

</div>

> [@jmooring](#):
>
> but you might consider using [tocbot.js](https://tscanlin.github.io/tocbot/)

I will try this.

---

<div class="post-metadata">

**Author:** ![system](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/system/32/1_2.png) [@system](https://discourse.gohugo.io/u/system)\
**Post date:** [October 17, 2024, 6:16am UTC](https://discourse.gohugo.io/t/can-hugo-include-shortcode-headings-in-toc/51940/9 "2024-10-17T06:16:30Z")

</div>

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