Use Zola - Githubissues

Zola is another static site generator. I found it recently and used it to make the new Codewars blog.

After experimenting more with Zola, I decided to switch the docs to it. This issue describes Zola, what to expect from the migration, and keeps track of the progress.

Markdown Based

Contents are generated from Markdown files under content/ just like Gridsome we currently use. For templating, Zola uses a simple template engine called Tera with a syntax inspired by Jinja2.

Markdown files need some minor changes, but I'll do that myself when migrating.

Augmented Markdown

Markdown is great for writing docs, but sometimes we need to add extra stuff. For example, we already have the following in many files:

<div class="block dark:hidden">

![Example](example-light.png)

</div>
<div class="hidden dark:block">

![Example](example-dark.png)

</div>

to show images based on the current theme.

Zola allows augmenting Markdown with shortcodes (small HTML/Markdown templates) as needed. So, when we need something extra, we can simply create reusable shortcodes and call them from within Markdown files. Then the above becomes

{{ figure(src="example.png", themed=true, alt="Example") }}

figure is a custom shortcode that expands to <img>s inside a <figure>. It handles image placement, captioning, generating responsive images, and theming based on a naming convention.

Gridsome allows something similar by using Vue components in Markdown, but requires a different Markdown plugin and didn't work well with the existing code.

I wouldn't want to add too many of these, but it's nice to have something that's easy to implement when we need them.

For now, we'll have:

figure(src: string, themed?: bool = false, alt?: string)
container(type: note|tip|info|warning|danger, title?: string) replaces ::: container blocks
anchored(id: string, text: string) (see #157)

Build Speed

Zola is fast. The blog doesn't have many pages, so it only takes milliseconds to rebuild on change. The docs take a few seconds, but it's still so much faster than Gridsome. This is significant for us because we usually build many times on Netlify per PR. It's better to keep the build time low to see the preview faster and to save money.

Simplicity

Gridsome provides a lot with Vue + GraphQL. It gives you many options to do anything. But we don't really need them. Also, Gridsome kind of forces you to use GraphQL for everything and this made the setup overcomplicated by having separate data/. I honestly don't like it.

Zola is opinionated and simple. The maintainer chooses the features carefully. It's much easier to figure out how to do certain things. I should be able to get rid of data/ and use the frontmatter as a data source. The generated site is very light weight with minimal JS.

Navigation

We currently need to manually configure sidebars and prev/next links. I'd like to automate this based on the directory structure and few options.

For the sidebar, I'll add some links that's always shown under the list of related pages.

"Index" is the table of contents for the entire docs.

Search

Current search isn't great because it only looks at the headings. The client-side search for static sites usually requires you to build a huge JS/JSON index file if you wanted to do a full-text search. I was originally going to sign up for DocSearch (#4) once we have more contents.

Zola has built-in support for search with elasticlunr.js. But I didn't like it because:

elasticlunr.js is not maintained anymore
the index file is a huge JS
need to implement search using the index and displaying the result

I recently found Stork that uses binary index and WASM on the client side. It doesn't require parsing huge JS, works by just including and registering the index, is easy to theme, and is fast. One problem was, to build the index, it requires a config file that lists all the pages to index in TOML. I'm not sure if that's possible with Gridsome, but I got it working with Zola.

Meta (Documenting the Docs)

I'll start writing how this all works (#89).

codewars / docs

Use Zola #248