Proposal: Add "ContentData" to customize TableOfContents

[satotake]

This is proposal. Further improvements will be required.
Any comments are welcome.

Add new Page Param ".TableOfContentsCollection" with goldmark.
This enables users to customize table of contents as they like.
You can be used it in shortcodes but have to use with {{< >}} (as non-markdown shortcode) because headers in contents cannot be determined until markdown shortcodes ({{% %}}) are rendered.

First, I was tackling the issue #7095 . It was harder than it looks.
Rather than fixing the single issue, I added the new param that gives Hugo some flexibility

Here is usage example

---

Addresses #7095, #6811, #6081, #225

[bep]

I agree about the general idea, but not the param bit.

I have another issue somewhere describing a "page map"; the golden end goal would be that you could do

{{ range .Page.ContentMap.Headings }}

{{ end }}

Etc. etc. in a very efficient way. I need some help on the Goldmark side to get to the above, but it would be really cool.

That said, I admit that the above ideal end goal may be some time in the future, so I'm open to adding ToC as the first step ... If we could agree on a name (not params) for the container collection, e.g.:

{{ range .Page.ContentData.TableOfContents }}
{{ end }}

[satotake]

Thank you for commenting @bep

it would be really cool.

Absolutely.
I am afraid that I cannot find your description even now but I hope it will be done in the future.

I agree with your suggestions. Especially, I am appreciating your attention to names which interface with general user.

I will update.

[satotake]

Done.

• ContentData was adopted
• TableOfContentsCollection (as param?) was removed
• PR title was changed

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[bambooom]

Hi, will this feature be added in the future? I'd like to customize toc content by shortcode as I need to filter out some headings.

I've tried this solution, but it throws out error can't evaluate field Content in type *hugolib.ShortcodeWithPage.
If I change to use .Page.Content instead of .Content, there won't be error, but the toc content is never rendered.

[reinhrst]

Thanks for the link @bambooom , it works for me (in a partial, not in a shortcode). Expanded a bit to also catch the tag name and make it configurable (not sure how to access the markup.tableOfContents settings, so using custom params. It (obviously) needs CSS to style now.

{{ $startLevel := .Site.Params.tocStartLevel | default 2 }}
{{ $endLevel := .Site.Params.tocEndLevel | default 3 }}
{{ $tagRe := printf "h[%d-%d]" $startLevel $endLevel }}
{{ $tocRe := printf "<%s.*?>(.|\n])+?</%s>" $tagRe $tagRe }}
{{ $headers := findRE $tocRe .Content   }}
<toc>
      <ul class="menu-list">
          <li class="toc-h0"><a href="#page-top">{{.Title}}</a></li>
          {{ range $headers }}
              {{ $tagname := substr . 1 2 }}
              {{ $header := . | plainify | htmlUnescape }}
              <li class="toc-{{$tagname}}">
                  <a href='#{{ $header | anchorize }}'>{{ $header }}</a>
              </li>
        {{ end }}
      </ul>
</toc>

Still feels like a hack though; would be great if something like this proposal were to be added.

[Asday]

I'd also like this feature to render only parts of a table of contents. My use case is a "here's what's in this part of the document" at the top of a section, and the table of contents for only that section. Currently what I'm doing is rendering the whole table of contents where I want it with a shortcode, then copy pasting the rendered HTML into another shortcode and editing it, and then using that shortcode for the final render, which really is kinda sub-optimal.

(Note "section" here is the English use of the word, not the hugo use).

[github-actions]

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