Setting Up Zola

01/07/2021, Thu

Categories: #cms

Static Site Generator Configuration

Zola is a decent static site generator written in Rust. This post will list some of my impressions and settings I made to get it customized to my liking to emulate the look and feel of my previous blog design.

Generating a new project

After using the init command, empty folders are generated, but it isn't quite clear on what needs to be modified. Running the server on the newly generated project yields a welcome page, but the physical page is not to be found in any folder. To get started quickly, I recommend that you use a theme and then customize it to your needs.

Adding posts to the index page

The way posts are display are dependent on how they are nested within the top level "content" folder. Having the "content/blog" route entails that you have a "blog" folder inside the "content" folder. Each url route's configuration is determined by a "_index.md" that lies within each nested folder. This pattern makes for intuitive discernment of content that is in your site.

When you have the folder structure of "content/blog", the site's paginator needs to know that the posts content is one level below the "content" folder. Add the following to "content/blog/_index.md" allows for paginating the posts on the "index.html":

transparent = true

Mark the post's summary content

Generally, the index page where you list all the posts will have a quick blurb of the post's content instead of the entire post's listing. They tend to include only the first paragraph of text of the post for each of the paginated post.

By adding

<!-- more -->

In your post's markdown file, it specifies the point where you want the summary to end and this will truncate the paginated posts display on your "index.html".

Note on dates in the URL

Another issue is that there is a common pattern for blogs to have the date encoded into URL scheme.

Take this pattern for example: /2021/01/08/a-new-post

However, due to the explanation of the author of the Zola project, this doesn't seem to be a problem that will be addressed in the near future. https://github.com/getzola/zola/issues/635#issuecomment-524564469.

By forgoing this URL pattern, I have to use an alias field with a value of the old URL scheme in each of the post's front matter to redirect to the new path. This is done to not break the old URL links.

aliases = ["2016/12/06/README-md-Reuse/"]

Archives page

The "get_section" helper method comes in handy for globally retrieving the page of concern

{% set section = get_section(path="posts/_index.md") %}
<h2 id="title">{{section.title}}</h2>
{% for year, posts in section.pages | reverse | group_by(attribute="year") %}
...

Also in the associated "_index.md" file for that template, use the 'sort_by = "date"' key to perform the proper ordering

+++
title = "Archives"
template = "posts.html"
aliases = ['/archives']
transparent = true
sort_by = "date"
+++

Front matter in posts

Make sure that "[taxonomies]" and "[extra]" go below the other front matter keys in your post markdown files or else Zola will error out.

title = 'README.md Reuse'
description = "markdown reuse"
[taxonomies]

Code Blocks

Zola does not provide support for description titles headers. Get around this by adding a comment line on the top of the code blocks to describe what you code is about.

Assets

The "static" folder on the root level is where you should put all images or supporting site files for the site and posts.

Additional Notes

Link Checker

There is very convenient command built into Zola that can check whether links are dead within your posts

zola check

Documentation

The documentation on Tera, the templating engine used by Zola, is a good source to consult when you want to modify your templates.

Developing

When developing, use "http://127.0.0.1:1111/" instead of "http://localhost:1111/" URL in case you get a CORS asset error when accessing fonts.

Conclusion

Overall, Zola is a fast and compact static site generator that is easy to get started due to the ease of setup and configuration. No longer do you need to install NPM modules to get the right dependencies for your static site generator to get off the ground.

WH