I’ve just done a first pass porting my blog to Zola (see corte.si for the current version - the Zola version is not up yet). The previous version of the site was rendered using a static site generator I wrote myself in Python, and it’s remarkable how similar its approach was to Zola’s. Maybe there’s some ideal solution we’re all converging on.
Overall, the experience was great, and I’m very confident Zola was the right choice. That said, there were a few hitches and places where things could be improved - or perhaps, areas where I missed the right approach.
- Many of my posts are code and image heavy, or include a self-contained web app as an asset that is linked to in the post. These have to be kept in a directory, ideally co-located with the post. There’s a tracking issue for this, so it’s already on the radar. I also have assets co-located with posts that I don’t want rendered. One simple way to handle this would be to copy all files/directories, except for those named with a leading underscore. So,
_render.pydoes not (I often have a render step for posts).
- Many of my posts contain some HTML. A really serious issue for me is that there is no way to link to co-located assets from HTML using something like the Markdown @-path expansion. This in turn means that asset links are totally broken in the RSS feed (where absolute paths are required), unless I hard-code an absolute link for every reference in the HTML. I don’t think parsing the HTML to correct this is at all feasible, but perhaps there could be a flag on pages that does a first-pass render of the page using the template engine. So, if the frontmatter has
template=true, we render the page content as a template, which would let me expand paths wherever needed with
get_url. We then take the rendered output, and render the markdown just as we would for an ordinary post. This would also be wonderful for more complicated posts that include a render step, for instance when generating a table of assets (here’s an example of such a post from my blog.
- I feel that the ergonomics of @-path expansion could be improved. At the moment, these are a full path from the content base, but there’s no reason why they couldn’t be just a unique suffix. So, say we have paths
/content/dirtwo/posttwo/index.md. To link from one to two right now, we need a path
@/dirrone/postone/index.md. But we have a complete index of all pages, and there’s no reason not to just use a unique suffix. So
@/posttwo/index.mdwould link to posttwo, but
@/index.mdwould be an error, because it’s not a unique suffix. That way, posts can be moved around within the site without breaking all links, and you don’t have to continually type out long complete paths to cross-link between posts. As a corollary, I’d like to be able to cross-link between assets as well, to embed images from one post to another - so
Let me know if I’ve missed solutions to some of these issues. If features like the above seem like something that would fit Zola, I’d be happy to create some tracking issues and work up implementations.