Understanding transparent mode

I’m trying to understand how transparent works, but I think I’m missing something.

I have a content structure that looks like this:


The articles index has a page template articles.html and a section template articles-list.html.

If I understand correctly, the main content index is a section which maps to index.html, and transparent bubbles up a single-level child section to its parent, so if I set the _index.md of /articles to transparent, I should be able to reach its content from index.html, is that correct? I feel like I’m missing something obvious about how to access the content, or I don’t understand how transparent works.

All I’m trying to do is display the list of my /articles content at the base url (example.com), but I want to organize the files and have the permalinks point to each article at the section url (example.com/articles/one).

There may be another/better way to do this but transparent seemed “right” to me based on how I read the docs.

Any insight would be appreciated. Thank you for all the hard work on Zola!

No, in transparent mode you just access to pages inside folder. You can display its in templates as you want. You can think about transparent mode like a way to catalogize your pages for you, not for website. I mean if I want to structure some content by years inside one big section - transparent folders would be a good way. But users can get pages inside a big section only.

But when you ask site.com/articles it might be useful to get redirect to first page of transparent section (you can add redirect_to = "acrticle/page/"

I think you’re understanding it mostly correctly @Ziggy

Setting a section to transparent doesn’t change anything to it. The only thing it does is pass the pages of that section to its parent section in addition. In practice, they get added to the section.pages variable if you are not using pagination. It becomes more complex if you want to paginate the homepage in your example but not much.

Ahh OK, that mental model makes sense to me. I got it working and I think I understand the access pattern more clearly now. Thank you both!

What would you expect to see in my case? Pagination was my next step once I could access the /articles content from the index section and it appears to be working OK for me. In my index.html I have as a test:

{% extends "base.html" %}

{% block content %}

    {% for page in paginator.pages %}

        <a href="{{ page.permalink }}">{{ page.title }}</a>

    {% endfor %}

    {% if paginator.previous %}
        <a href="{{ paginator.previous }}">Newer</a>
    {% endif %}

    {% if paginator.next %}
        <a href="{{ paginator.next }}">Older</a>
    {% endif %}

%{ endblock content %}

And my root _index.md has:

sort_by = "date"
paginate_by = 3
paginate_path = ""

So the final URL looks like: example.com and example.com/2/which is what I was going for. Curious what you might have expected in case there’s a gotcha I’m not seeing yet.

Nope that’s fine, the only gotcha is people expecitng to paginate on the section that is transparent and expecting it to happen automatically on the parent. Not a big gotcha :slight_smile:

That is what I was expecting before this conversation :slight_smile:

I appreciate the clarification, thank you!