Debloated Markdown Blog with Zola

2021-04-14

With the current state of the web, a lot of non-free Javascript has to be run to do very simple things like rendering a blog. In an effort toward ever minimal and debloated software we have migrated this blog away from Next.js and to Zola, which is a markdown blog system written in Rust that has a relatively minimal footprint.

First a quick comparison of the pros and cons:

Zola (minimal)

Pros

  • Javascript not required
  • Builds are super fast
  • No complex package system to manage, runs with two binaries
  • Still can use node.js libraries to compile CSS like Tailwindcss (but result has no javascript)
  • Result is totally free even without posting the code since there is no script delivered to the browser

Cons

  • You sometimes probably want to run code on the client. For a blog this is not required (or probably even recommended)
  • You'll still re-introduce bad javascript if you want to track view counts through something like Google AdSense

Next.js (bloated for a blog)

Pros

  • Easier integration with other web libraries like Tailwindcss / React

Cons

  • A huge amount of unused features for a blog -- eg you don't need React, you don't' need to be running Javascript to transition pages etc.
  • Larger payload delivery / slower pages. (Since you also have to send the Javascript)

Getting Started

This blog is built in two pieces. Zola templates to render the markdown posts, and Tailwindcss to compile only the necessary styles that we use (and make the css a bit less of a pain).

To make a similar blog, just follow the Zola instructions and get the project set up.

And along side that you'll need to run npx tailwindcss init to get the css framework set up. This will generate a file named tailwind.config.js which contains the configuration for Tailwind. There you'll need to set it to purge from the HTML template sources like:

module.exports = {
  purge: [
    './templates/**/*.html'
  ],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

Next, you'll need to create your style file that tells tailwind where to compile from: styles/tailwind.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

From there you can then use any tailwind styles in your templates. Eg for the blog post:

{% extends "base.html" %}

{% block content %}
<h1 class="text-3xl">
  {{ page.title }}
</h1>
<p class="text-gray-600 text-sm"><strong>{{ page.date }}</strong></p>
<article>
{{ page.content | safe }}
</article>
{% endblock content %}

Then to compile the styles for production simply run:

npx tailwindcss-cli@latest build ./styles/tailwind.css -o ./static/tailwind.css

This will output a static css file with only the required files. The only remaining step is to include this in the production build but including it in the head:

<head>
  <link href="/tailwind.css" rel="stylesheet">
</head>

Then you can simply zola build and your blog will be fully rendered in the public directory. You can look up static hosting possibilities in the Zola documentation. This site is hosted on Vercel, which is good / affordable, but sort of expects that you are using Javascritpt to track users so can't count metrics on the server side.

What I would probably recommend is hosting it in a simple VPS and then setting up NGINX to simply anonymously count page views so you can get an accurate picture of how many visitors you have to your site without also letting Google get it's hands in your data / take advantage of your readers.