Adding anchors to non-header (with ToC support)

support
1

Hi. I want my “details“ shortcode to work as a markdown header, i.e. it should automatically generate the anchor link from its summary and add it to the table of contents. Ideally if user follows the anchor the details should open.

I copied details.html as details_header.html with the following content:

<details {{ if or (.Get "open") (in .Params "open") }}open{{ end }}>
  {{- $summary := cond .IsNamedParams (.Get "title") (.Get 0) -}}
  <summary id="{{ .Get "link" | safeURL }}">
  {{ $summary }}
  <a class="anchor" href="#{{ .Get "link" }}">#</a>
  </summary>
  <div class="markdown-inner">
    {{ .InnerDeindent | safeHTML -}}
  </div>
</details>

I use it like this:

{{% details_header title="Test" link="test" %}}
{{% /details_header %}}

Of course in this case I need to provide a link by myself. And this section doesn’t appear in ToC. How do I control what goes to ToC and what function should I use to generate a link from the text the same way it’s done for markdown headings?

I’m using hugo book if it matters.

2

The TOC picks up heading elements (h1-h6 depending on site config). How does the above relate to a heading element?

3

I want details’ title to act as heading.

So when I write something like

{{% details_header title="Test" %}}
{{% /details_header %}}

the “Test” will be automatically added to ToC with an anchor. So when the user clicks on Test in the ToC it goes to the anchor.

Sure I can add the markdown heading element inside the details shortcode and it works

{{% details title="Header" %}}

### Header

{{% /details %}}

But it means it shows the title twice.

4

Try this:

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

The above generates valid HTML.

Files of interest:

  • layouts/_shortcodes/details.html (based on Hugo’s embedded details shortcode)
  • hugo.toml (lines 5-6)
  • baseof.html (lines 7-13)
5

Thanks for taking your time on making the example!

Just in case someone else is trying out this example - it doesn’t work on hugo 0.141.0. I had to update to the latest version (0.148.2 at the moment).

Also I’m using hugo-book theme and I had to update _default/_markup/render-heading.html with the latest hugo-book version to make the css style forwardable (related diff Introduce landing page and card shortcode · alex-shpak/hugo-book@4722375 · GitHub ).

The only thing left is to make the details open when user follows the anchor. Browsers seem to support automatically opening the details if the anchor is in the details content. But with our current approach the anchor becomes part of the summary, so it doesn’t work. Hypothetical solution is to make an empty heading element with the anchor generated from the title/summary and put it inside the details contents, but I don’t know if it’s possible.

I found the similar topic but it seems to be unresolved Automatic anchor links for paragraphs?

6

You could move the heading element into the details content and set its visibility to hidden, but then the browser will scroll to the details content instead of the summary.

A better approach is to use JavaScript to control what happens when you click on a TOC link. I’ve updated the example; try it again.

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

Thanks for JavaScript based solution! Marking it as solved.