ainame's Blog

Tuzuru static blog generator beta release

By ainame / Published on 7 September 2025

I’ve released the beta version (^1) of Tuzuru, a static blog generator (0.1.2). It’s a CLI for people who want to set up a simple blog on GitHub Pages. Since I built it, I’d like to introduce it briefly here.

https://github.com/ainame/tuzuru

Tuzuru is a CLI in the static site generator family, but as it doesn’t aim to support anything beyond blogs, I’m calling it a static blog generator. This post was generated with Tuzuru and is hosted on GitHub Pages with a custom domain.

If you’ve been thinking of hosting a blog on GitHub Pages, I’d appreciate it if you gave it a try. Feedback is very welcome.


(I generated the logo with Gemini)

(^1) Until now I’ve been developing quickly on the main branch, but from here I plan to switch to a lightweight PR-based workflow.

Features

I once tried to revive a Hugo-based blog and gave up, which led me to start building Tuzuru. I’ve designed it to be as simple to use as I can make it. In short:

  • Write posts in plain Markdown; intuitive
    • No need to learn or remember YAML front matter syntax
    • Instead, post dates and author names are taken from git log
  • Works out of the box with minimal configuration
    • Automatically generates the home page plus yearly and category lists
    • Simple layout
  • Written in Swift
    • Reasonably fast (I haven’t benchmarked it; the places that call git commands may be the bottleneck)
    • On Linux it’s a static binary via the Static Linux SDK, so installation is straightforward

Demo

Here’s a separate, random AI-generated demo page I’m hosting:
https://ainame.github.io/tuzuru-demo/

Main commands

At the moment the following subcommands are available:

  • tuzuru - runs tuzuru generate
  • tuzuru init - initialises a project by creating the config file (tuzuru.json) and templates
  • tuzuru generate - converts Markdown files under contents/ to HTML and generates listing pages
  • tuzuru amend - a way to change a post’s date and author in Tuzuru later without rewriting Git history (creates a Git commit with a marker)
  • tuzuru import - a simple importer for Markdown written for Hugo
  • tuzuru serve - a built-in HTTP server for previews

Also:

  • You can create pages that aren’t listed automatically (like /about)
  • Links to X are automatically converted into embedded HTML
  • The built-in preview server supports hot reload
  • CSS cache busting
  • Open Graph tags
  • Automatic generation of sitemap.xml
  • Installation via Homebrew or npm

Simple deployment to GitHub Pages

Enable GitHub Pages in your repository settings, then add this to .github/workflows/deploy.yml to deploy.

The ainame/tuzuru repository provides a reusable action for deployment, so you only need two steps: actions/checkout and ainame/Tuzuru/.github/actions/tuzuru-deploy.

name: Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: ainame/Tuzuru/.github/actions/tuzuru-deploy@0.1.2

Summary

It’s simple, but it covers the features I wanted. If you try it and find it useful, a star would be appreciated.

👉 GitHub: ainame/tuzuru