FR: Table of Contents
stevenroose opened this issue · comments
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 🙏
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.
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?
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 ofHeader
objects that Zola generates automatically based on the headings in the markdown content. EachHeader
object has a few fields.
The line of code you shared is checking whether two conditions are met:
page.extra.toc = true
: the ToC should be rendered at the top of the article (defaults tofalse
)page.toc
: the page actually has a ToC (the array ofHeader
). 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).
The guide to all of tabi's settings is live! Check it out: Mastering tabi Settings: A Comprehensive Guide