Confused about internal linking - help

I’m porting a website from GitHub Pages (using Jekyll) to Zola as an test, and I seem to be getting really stuck with reliably linking up and down the structure of pages.

The existing site is visible at

Trying to go from the homepage to a sub-page (the “modules” link, for example) tends to be fine, but then from the module to another file things go very strange.

Further more, a lot of the leaf-node pages have anchors for the page they are on, but rather than just jumping to the header, it causes a page reload. I think this has something to do with the presence or absence of trailing slashes. How is Zola supposed to handle this?

It’s likely that. Zola urls will end with /, so I guess the site redirects from no slash to slash and that’s the new page load you’re seeing. People usually just use the Zola generated URLs

Do you have an example? I’m doing tons of internal linking with the Zola docs at Overview | Zola and I haven’t seen issues

It’s a little hard to explain. The page structure is like this:

├── modules
│   ├──
│   ├──
│   ├──
│   ├──
│   ├──
│   ├──
│   ├──
│   ├──
│   ├──
│   ├──
│   └──

If you navigate to “/modules/audio”, you end up in the modules/ file, which has a “back” link intended to take you to the modules/ file, defined like this in the markdown: [back](.)

That . works differently if the URL currently has a trailing slash, vs when it doesn’t:

/modules/audio → you end up at the index page.
/modules/audio/ → you just reload the audio page again. no way back.

I’m expecting to move directories around in the future, so links need to remain relative. How is this supposed to be handled?

The way Zola internal linking is built is to refer to the .md file.
In that case, modules/ should maybe be modules/ instead so it’s a section and all the other files are children of it.
Then to go back it would be [back](@/modules/ This means that the filepath would need to be repeated but you would get an error if you move it without correcting them.

That’s not ideal for my use-case unfortunately.

In the future, I’d like to break the site up into “versions” (so I can retain older documentation while working on new stuff), which means I need to be able to move/duplicate the directories around without breaking their structure AND there will be a set of pages which will be sitting where the old ones were, so there won’t be errors created, and all the links will point to the wrong files.

If this isn’t something Zola can handle, I think I’ll need to seek another solution.

It would work, it just adds one search & replace for [back](......) to add the version number when moving to a new version folder.

Hello @keats -

cause this is my first message: thank you for Zola! :slight_smile: I’m afraid, I’ve got the same issue - in need for a solution. To provide further context: I’ve got 1000 densely linked notes. My note editing system (backend) relies on standard markdown link format, too.

If I followed your search & replace proposal, I’d break the backend of the site I’m trying to build with Zola.So, I’d have to work with duplicate content. Which adds a dependency to something else.

If I post-processed links as you suggested (search & replace), I’d add a dependency. To Python, PHP or whatever.

While I understand the rationale behind the internal link format as implemented, doesn’t it contradict the overarching design goals you had?

“no dependencies” - unless it enforces workarounds
“easy of use” - absolutely, loving it. Except:
“flexibility - gets out of your way” - I’m afraid, this issue is an obstacle
"scalability - shouldn’t this also include content creation at scale? #workflow

:wink: :kissing_closed_eyes:

The way I see it, Zola is perfect as a digital gardening solution. Thus, for a lot of people out there. I’m currently building a well documented package to make this as easy as possible for non-tech-savvy folks. Thus: No dependencies. Help?!

And yeah, it seems to be just one minor detail. Yet one with a long tail of consequences.I mean, looking around I’m not the only person with this road-block.

I’m sure there must be a way to integrate an option, a filter or something? Or: did I miss anything?

My goal is this: Notes —

Much love from northern Germany