biisan

biisan is a static site generator for blogs written in reStructuredText or Markdown. It converts documents into model objects and renders them with replaceable Jinja templates.

日本語

Requirements

• Python 3.11 or later

Features

• Write entries in reStructuredText or GitHub Flavored Markdown
• Render pages with replaceable Jinja templates
• Generate the blog index, monthly archives, a complete entry list, RSS feeds, and a sitemap
• Generate a separate RSS feed for every entry category
• Add custom metadata to entries and use it from templates
• Register custom Jinja filters and global functions
• Parse entries in parallel and avoid rewriting unchanged pages with a SHA-256 render cache

Install

Create a virtual environment and install biisan from PyPI:

python -m venv .venv
source .venv/bin/activate
python -m pip install biisan

Create a site

Run the initializer in the directory where you want the site project:

python -m biisan.main

It creates this structure:

biisan_data/
├── data/
│   ├── biisan_local_settings.py
│   ├── blog/
│   ├── extra/
│   │   └── about.rst
│   └── templates/
└── out/

Add a reStructuredText entry to biisan_data/data/blog/:

My first entry
==============

:slug: my-first-entry
:date: 2026-09-19 13:00
:author: Your name
:category: notes

Hello, world!

Markdown entries use YAML front matter:

---
slug: my-markdown-entry
date: 2026-09-19 14:00
author: Your name
category: notes
---

# My Markdown entry

Hello, Markdown!

Generate the site from the data directory:

cd biisan_data/data
export BIISAN_SETTINGS_MODULE=biisan_local_settings
python -m biisan.generate

Entry URLs are derived from each entry's date and slug.

Markdown supports headings, paragraphs, emphasis, links, images, lists, block quotes, fenced code blocks, tables, thematic breaks, and inline or block HTML. Raw HTML is copied to the generated page, so use Markdown input from trusted authors.

Generated files

A build writes these pages under biisan_data/out/:

An entry with category: notes produces /api/feed/notes/index.xml. The number of entries included in each RSS feed is controlled by latest_list_count.

Each rendered entry and extra page also has a .biisan.raw.sha256 file. On the next build, biisan skips minification and writing when the rendered content has not changed.

Customize

Edit biisan_local_settings.py to change the site configuration. Common settings are:

Put templates with the same relative path as the bundled templates in data/templates/ to override them. The generated settings file adds that directory before the built-in template directory.

Additional reStructuredText docinfo or Markdown front-matter fields are available to templates as attributes of the story object, provided their names do not conflict with built-in attributes.

For example, category is available as element.category in an entry template. Test optional metadata before reading it:

{% if element.has_additional_meta("og_image") %}
  <meta property="og:image" content="{{ element.og_image }}">
{% endif %}

Development

The repository uses uv. Dependency resolution excludes distributions uploaded within the last seven days.

uv sync --locked
uv run pytest
uv run ruff check src tests
uv run pyrefly check
uv build
uv run twine check dist/*

The test suite is run on Python 3.11 through 3.14.

License

MIT