I was hoping to start a thread that others may find and share their input regarding the next major version of Zola. In other words, if breaking changes to Zola are allowed, what would be something to change?
Right now, I know of Tera 2.0.0 is probably the big one (and there’s been discussion around that on GitHub).
What else?
Here are a few I thought of:
explanation: dates are allowed in the filename/directory-name of pages, which are ignored in compiled site’s URL. However most zola functions require the local file path. This may seem a small difference but to me it can create a lot of headaches and be the source of much user error.
proposal: in the file searching logic, make fully qualified, file path name the highest priority, but add a fallback to the url path when the site is compiled (without the date in the page file or directory name). Bonus points for aliases too.
For example
get_page(path="foo/2025-02-01_bar/index.md")get_page(path="foo/bar/")["click me"](@/foo/2025-02-01_bar/index.md)["click me"](@/foo/bar/)would all work the same, or perhaps there would be separate url and file parameters…
explanation: currently you can do this [click me](@/_index.md), but using the same internal link syntax  is allowed but isn’t treated as an internal link, which is almost certainly not what what anyone would want. Even in the documentation it states
In practice this means that
@/some/image.jpg,/content/some/image.jpgandcontent/some/image.jpgwill point to the same thing.
But I’m not exactly sure where the internal link syntax actually has an effect on anything besides markdown files.
proposal: link validation is super important, and broken image links are no exception. It would make sense to treat links with internal link syntax as true internal links and validate there is an actual image there. Even better if the internal link syntax could be used for any resource as a shorthand for specifying that you want the link to be validated.
required function parameter to important functions (e.g. get_page, get_section, get_url)explanation: the first two functions (get_page and get_section) have no option to fail without halting compilation if there is no page/section at that path. On the other hand get_url will happily create URLs that won’t ever exist (or are not even valid URLs).
proposal: a required parameter exists for any function that takes a path arg. If required is true then failure to resolve the path breaks compilation, and if required then failure to resolve is ignored and the function can return null or an invalid URL, depending on the case.
explanation: as far as I know all feeds share the same template and you can only control the filename. So if you have a complicated site in terms of feeds it feels unnecessarily hard to manage all that complexity.
proposal: associate a feed with a template in a similar way to taxonomies perhaps? Taxonomies just use a fixed directory structure under /templates/ to determine which taxonomy gets used, and there’s a backup of taxonomy-list/single that exists as a default. I think most people are fine with just the default atom.xml, so that should stay, but not being able to separate feed templates in more complicated scenarios feels cruel. Tell me if I’m wrong and this is possible. I also saw a proposal in the GH issues about calendar feeds that made me think of this issue as well.
explanation: This has been discussed a lot in the forums, but I actually like sections vs pages and I think conceptually it’s a net positive, especially when you use other features like feeds. However I think there is some small amount of friction and that’s because there are some awkward API differences between the three. Also the main functions of get_page, get_section require you to keep in your head some kind of mental model all the time of local file paths vs compiled url paths, such as adding _index.md for sections as well as many possible values for pages. Not to mention point #1 above about how the local file paths can differ from the compiled url paths, and how there’s no way to call get_page or get_section and have those calls fail.
proposal: I would have to look more closely but for example there has been a lot of chatter about the anchor links only being at the section level, but also paths_keep_dates is only available at the general level, when it would be much much more valuable at the section level. This post though is already too long so I’ll just leave the idea there.
Thanks for reading!