Zolarwind

A localizable blog theme using Tailwind CSS for styling and KaTex for math

Author: Thomas Weitzel

License: MIT

Homepage: https://github.com/thomasweitzel/zolarwind

Live Demo: https://pureandroid.com

Last updated: 2024-11-18T05:58:26Z

A screenshot of how the theme looks like

The Zolarwind Theme for Zola

Welcome to Zolarwind, the simple Zola blog theme with Tailwind CSS and KaTex support. This theme is for Zola users aiming to have a nice blog design powered by Tailwind CSS. It seamlessly integrates with Mermaid, enabling the creation of various diagrams directly within your blog posts using a Markdown-inspired syntax. Additionally, the theme smoothly integrates math formulas using KaTex. Most importantly, while the theme is designed to be easily localizable, you can choose your preferred language setting for a consistent blog experience.

Features:

Table of Contents:

Demo Website

You can see the theme in action on my personal website. The site uses the German language.

Prerequisites

To use the theme, you need some software pre-installed:

Installation

  1. Clone this theme repository with e.g. git@github.com:thomasweitzel/zolarwind.git. Or download it from https://github.com/thomasweitzel/zolarwind.

  2. Make adjustments to the config.toml file as needed. To run the theme as a standalone site, you need to adjust the base_url to your domain. If you want to try it out on your local machine, you can leave it as is. Just run zola serve from the theme's root directory.

Configuration

Your config.toml file is crucial in customizing the Zola site. Here's a breakdown of the configuration settings tailored for this theme:

Basic Configuration:

Markdown Configuration:

Extra Configuration:

The [extra] section is where you can place any custom variables you want to be accessible in your templates.

Front matter

For blog posts (Markdown files in folder content/blog), this theme uses a directory structure where each post has its own folder. This way, I have all resources for a post in one place. It can include images, videos, and other files.

Each post is associated with an image displayed on the blog's main page and on the post's detail page. If you do not provide an image under extra.image, a default image is used instead.

Localization

Consider this text on a page where a blog post is published as an example: Published on July 04, 2023; 1,234 words. If your blog is in the German language, you want to have Veröffentlicht am 04. Juli 2023; 1.234 Wörter instead. Not only the text should be translated, but also the date and number formats are different. And you want a text like 1 word or 1 Wort, because the singular form should be used where applicable. This theme takes care of that.

To localize your blog with this theme:

  1. Pick your desired language by setting the default_language in config.toml. As of now, English (en) and German (de) have language resources available in the i18n directory. If your language is not supported yet, just create a new resource file with your translations. Use the file en.toml as a template for your own translations. Use the correct language code for the file name, e.g. eo.toml for Esperanto. This theme supports only languages that read from left-to-right (ltr).

  2. The theme will automatically display all theme-specific string resources in the chosen language.

  3. The content that you provide should match this language. But that is your responsibility. The theme will not translate your content.

If you need to define your own date format, look here for supported specifiers.

Integrating the theme folder

This project is structured as a stand-alone Zola site. This section is for those who might want to integrate the theme into an existing Zola website. You can do so by moving the relevant theme files to the themes/zolarwind directory. All other files stay in the root directory. If you have your own files there, you need to merge them with the ones from this theme. You also need to adjust the config.toml and package.json files in the root accordingly.

I will only show you the relevant directories that need to be moved. This is the directory structure of the stand-alone site, where the theme is in the root directory:

/
├── css
├── i18n
├── static
│   ├── css
│   ├── img
│   └── js
├── syntaxes
├── templates
└── theme.toml

Create a new directory themes/zolarwind and move the following files and directories there:

/
├── static
│   └── css
└── themes
    └── zolarwind
        ├── css
        ├── i18n
        ├── static
        │   ├── img
        │   └── js
        ├── syntaxes
        ├── templates
        └── theme.toml

The static/css directory is a special case. It contains the generated Tailwind CSS file with the name generated.css. It will stay in its original location. This file is generated from the file css/main.css, which is the input for the CSS generation. The generation process can be triggered with a script in the package.json file. You only need to adjust and run the script in package.json if you make changes to the theme's template files or use new Tailwind CSS classes directly in your content files. Since the source file css/main.css has moved to the directory themes/zolarwind/css/main.css, we need to adjust the script in package.json accordingly.

This is what the relevant part of it looks like for the stand-alone site:

"scripts": {
  "css:build": "npx tailwindcss -i ./css/main.css -o ./static/css/generated.css --minify",
  "css:watch": "npx tailwindcss -i ./css/main.css -o ./static/css/generated.css --watch",
  "server": "zola serve"
}

Now change it so that the input file css/main.css will be the file themes/zolarwind/css/main.css:

"scripts": {
  "css:build": "npx tailwindcss -i ./themes/zolarwind/css/main.css -o ./static/css/generated.css --minify",
  "css:watch": "npx tailwindcss -i ./themes/zolarwind/css/main.css -o ./static/css/generated.css --watch",
  "server": "zola serve"
}

Since you now use Zolarwind as a theme, you need to declare it in the config.toml file. The theme's files have moved to the directory themes/zolarwind, so you need to adjust the only reference to the theme's files in the config.toml file accordingly by changing the path_language_resources entry:

# The site theme to use
theme = "zolarwind"

# ...

# Path to the language resource files
path_language_resources = "themes/zolarwind/i18n/"

Development

If you want to adjust the CSS of the theme to your needs, you will need to edit the files in the templates and css directories. While you do this, you should make sure that the CSS file static/css/generated.css is up to date. This file is generated from the file css/main.css, and all the files that are configured as a pattern in tailwind.config.js:

So whenever one of these files changes, you need to run the script css:build from the package.json file. To achieve this, you need to have Node.js and all dependencies from package.json installed (with npm install). Then you can run the script with npm run css:watch. It monitors all files mentioned above and triggers the CSS generation whenever a relevant file changes. This ensures, that the file static/css/generated.css is always up to date.

I recommend having two terminals open. In one terminal, run npm run server - or just zola serve - to start the Zola server. In the other terminal, run npm run css:watch to start the CSS generation whenever a relevant file changes.

That way, your local web browser will automatically reload the page with the updated CSS whenever you change a file.

Remarks

Typography for Markdown

I'm not using @tailwindcss/typography for styling of Markdown files. I don't like how it looks. Instead, I use @apply in the css/main.css file. The @apply directive in Tailwind CSS enables you to compose utility classes into custom CSS classes. This makes it possible to apply multiple utility styles within a single class, making it efficient to style Markdown content.

This approach has pros and cons. But it gives me fine-grained control over how the result looks like. While it is time-consuming, I prefer this solution over the @tailwindcss/typography plugin.

Yes, I'm reinventing the wheel here, because for common typographic patterns, I'm just recreating what's already provided by the typography plugin.

Serve KaTex files locally

All KaTex files are included in the static directory for this theme. Using KaTeX (or any other library) by serving it from a Content Delivery Network (CDN) has implications concerning the General Data Protection Regulation (GDPR) and the use of cookies:

Contributing

Contributions are always welcome! If you see areas of improvement or want to add features, please submit a PR.

I'm especially interested in more translations. See folder i18n for what's available and what is not. Use the file en.toml as a template for your own translations.

License

This theme is under the MIT License. For details, please refer to the LICENSE file.