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 https://domeengine.com

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:

.
├── _index.md
├── faq.md
├── getting-started.md
├── installation.md
├── modules
│   ├── async.md
│   ├── audio.md
│   ├── dome.md
│   ├── graphics.md
│   ├── index.md
│   ├── input.md
│   ├── io.md
│   ├── json.md
│   ├── math.md
│   ├── plugin.md
│   └── random.md

If you navigate to “/modules/audio”, you end up in the modules/audio.md file, which has a “back” link intended to take you to the modules/index.md 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/index.md should maybe be modules/_index.md instead so it’s a section and all the other files are children of it.
Then to go back it would be [back](@/modules/_index.md). 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.