Balu's Logo

Zola Anchor Links

— , — 3 minutes to read

I tried adding anchor links to level two and three headers, because I really wanted to be able to link to sections on a page directly.

But I stumbled over a Zola concept that already confused me with Hugo before while doing so.

Zola has two types of organisational levels: Sections and pages.

Sections can contain subsections and pages. They have their own design templates and different front matter variables. They are the “branches” in Zola’s content tree.

Pages then are the “leaves” on those branches / sections. A page that is not inside of a section is “orphaned”. And this is what bit me in this case.

The problem

I had organized my content in the following way

  1. projects/_index.md for the “projects” section
  2. projects/website/index.md as page in this section
  3. projects/website/markdown.md as sibling page.

Zola now saw markdown.md as an orphaned page, because it is not directly under the “projects” section.

This meant that enabling insert_anchor_links = "heading" in projects/_index.md did not enable the anchor generation for the markdown.md page.

And since this variable only exists in the front matter for sections for some reason, there was no way to enable it for the page itself either.

The workaround

Thankfully “Spence” had asked about this concept on the Zola discourse group before and was able to point me in a direction to fix this.

The section front matter has a setting to disable the generation of the section homepage (as in index.html).

# If set to "true", the section homepage is rendered.
# Useful when the section is used to organize pages (not used directly).
render = true

While you can not have an _index.md and index.md in the same folder, you can have a website/_index.md and website.md with the section homepage rendering turned off. [I am not sure why one version works, but the other doesn’t though - they are kind of the same.]

So as a workaround I had to do the following:

  1. rename projects/website/index.md to projects/website.md (and fix some internal links on other pages)
  2. add projects/website/_index.md with the following front matter
    +++
title = "Placeholder to make this folder a section"
render = false
insert_anchor_links = "heading"
+++
  3. add insert_anchor_links to projects/_index.md

This made the website/ folder a section with markdown.md as an only page. And while website.md is generated in that folder too, it is part of the “projects” section.

So enabling insert_anchor_links in the “projects” and “website” sections then made Zola create anchor links in both of them.

This feels a little wrong, but it seems to work around my problem.