FR: Table of Contents

[stevenroose]

I see some themes have table of contents with like anchors for all the headings that optionally can be added in front of either a blog post of any page. I'd be very interested in having this 🙏

[stevenroose]

Oh, I see that it is already provided as an [extra] field, but not documented :)

Then maybe change this in an issue to move the field to the top-level front-matter because it seems that Zola supports this field natively.

You could support both I guess. Maybe I can fix that.

[stevenroose]

Wait, I'm confused, I see this line

51:        {% if page.extra.toc | default(value=false) and page.toc %}

What does that do/mean exactly? I thought the top-level toc field was a boolean too (because the page I linked does if page.toc { but I guess that check just checks if the variable is provided.

So the extra.toc boolean is necessary and we can't use the top-level toc fields?

[welpo]

Hey Steven!

• page.extra.toc is tabi's own boolean value to enable the ToC at the top of the page.

• page.toc is an array of Header objects that Zola generates automatically based on the headings in the markdown content. Each Header object has a few fields.

The line of code you shared is checking whether two conditions are met:

1. page.extra.toc = true: the ToC should be rendered at the top of the article (defaults to false)
2. page.toc: the page actually has a ToC (the array of Header). It will evaluate tofalse if it doesn't.

It's important to check the second part because not all pages have ToCs. For example, this page has no headers in the article, so it doesn't get a page.toc.

Zola doesn't actually have a built-in ToC. The page you linked simply shows an example as to how it could be implemented. In tabi, the ToC is built by the table_of_contents.html macro.

I'm glad you found the documentation on the theme's demo. In the future, I plan on adding a long page explaining all of tabi's features (both in config.toml and within the [extra] section of post's front matter).

[welpo]

The guide to all of tabi's settings is live! Check it out: Mastering tabi Settings: A Comprehensive Guide