Why are anchor links not available to pages?

1

I noticed in the documentation that insert_anchor_links are only available for sections. Is that, and , if so, why?

2

It applies to all pages in that section.

3

Ahh that makes so much more sense than what I thought. Ok, thank you.

4

That does not seem to be the case for me?

content/projects/_index.md # has `insert_anchor_links = "right"`
content/projects/website/index.md # gets anchor links
content/projects/website/markdown.md # does not get anchor links

Why does the markdown.md page not get anchor links?

I’m also confused why I can’t seem to set it globally and/or individually on each page, but only for sections.

Am I doing something wrong?

5

Hey Balu, I’m going to take a guess here as to why you’re seeing this.

website/index.md is a page under the root section /. Pages are allowed to be inside a directory for collocated assets, but they must be named index.md within that directory. This would make the url path /website. So it’s a page, under the root section. It’s the same thing as if you named that file /website.md.

On the other hand, website/markdown.md is a page without a section. There is no section inside the website directory. This is called an “orphan page”. From the documentation:

A section is created whenever a directory (or subdirectory) in the content section contains an _index.md file. If a directory does not contain an _index.md file, no section will be created, but Markdown files within that directory will still create pages (known as orphan pages).

So basically because it’s an orphan page (a page without a section) it isn’t inheriting the rules of the root section.

Hope that helps!

6

Thanks for your reply, but I am still confused.

The pages I was talking about were not under the root, but under their own section projects/. But I guess this doesn’t make a difference.

I am still not sure how to get the “orphaned page” to get anchor links. Setting insert_anchor_links in the page itself doesn’t work.

If I rename website/index.md into _index.md to make it a section, the markdown.md is not an orphan anymore and will get the anchored links (if enabled in website/_index.md, it does not seem to inherit from projects/_index.md)

But I am losing date and updated front matter since it is not a page anymore, but a section. Plus it is not listed as page the /projects section anymore, because well - it isn’t a page.

I don’t understand why insert_anchor_links is not a setting for the page itself? It only affects this page’s generation anyway?

7

Wups about the projects/ vs /, thanks for correcting my error. :grimacing:

Yes the insert_anchor_links won’t work for pages unfortunately.

Regarding the rest of your reply, the answer you seek may be in the section front matter documentation. Specifically, it seems that based on what you’re asking you might be able to use the render = false setting with your website section’s front matter, i.e. website/_index.md.

From the documentation:

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

However, you can’t have index.md file and a _index.md file in the same directory in Zola. To keep the same directory structure and go around this limitation you could rename your website page projects/website.md, and then put an empty section to organize all the pages nested under website, i.e. projects/website/_index.md. This will give you the url structure that you want, while keeping everything a page, and allowing the anchor links to be organized by sections.

(btw you can also take this a step further and mark the website section as transparent = true and it will just inherit everything from the projects section, I think).

The last thing I’ll add is that although I think zola v2 is planning on eliminating sections vs pages as concepts (which is probably the biggest source of friction among new users), it’s not such a terrible way to do things. This is just my opinion of course, and you do you, but the most natural way to solve your problem would be to make website an actual section, and sort of embrace the design, where pages are meant to only be the “leaves” of the tree.

Anyways, hopefully that solves your problem?

1 Like
8

No worries, I just thought I’d mention it in case it did matter :slight_smile:.

Do you know the reasoning behind that? It seems like a perfect setting for an individual page.

Yes, while this feels a little clunky, it seems to solve my issue.

What I did was

  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 content.
    +++
title = "Placeholder to make this folder a section"
render = false
insert_anchor_links = "right"
+++
  3. re-add insert_anchor_links = "right" to projects/_index.md

After that both projects/website/index.html and projects/website/markdown.html have anchor links added to the headers.

This doesn’t work, because it will also add the pages from the projects/website/ subsection to the projects/ section.

I am too new to Zola to decide on that. That said it can be confusing (different front matter, settings not being applied to orphaned pages, orphaned pages themselves, …) and results in issues like mine that require a “workaround”.

For example it now doesn’t make much sense, that I can’t have website/index.md and website/_index.md (with render = false), while website.md and website/_index.md are fine. :thinking:.

Thank you for pushing me in the right direction.

9

Just as a heads up:

While this works for me, it conflicts with Zola’s documentation on asset colocation. :slight_smile:

Pages with co-located assets should not be placed directly in their section directory (such as latest-experiment.md), but as an index.md file in a dedicated directory (latest-experiment/index.md), like so:

I am going to ignore this for now :wink: