Install and quickstart

Mizzen turns a folder of Markdown into a static docs site. It is a deterministic engine: the same input gives byte-identical output, and every page keeps the exact source position of its text. A theme draws the pages; Lateen is the default.

Requirements

• Node 24 or later. Mizzen is TypeScript that Node runs directly, so there is no build step and no compiler to install.
• Git, and a GitHub repository if you want to publish with GitHub Pages.

Install

npm install --save-dev @velella/mizzen @velella/lateen

Installing both packages in package.json pins the versions for the next person.

Write a page

Put a Markdown file in the folder. Front matter is optional; without it the title is the first h1.

---
title: Hello
description: The first page.
---

# Hello

Mizzen builds this file into `/hello/`.

Add a mizzen.yml at the root when you need a title, a base path, or a repository for "Edit this page" links:

title: My docs
url: https://example.github.io
base: /my-docs
repository:
  url: https://github.com/example/my-docs

Every key is in Configuration.

Check, preview, and build

npx mizzen check .
npx mizzen dev .
npx mizzen build . --out dist

check builds to a temporary folder and prints only the diagnostics, so it is the command to run before you commit. dev serves the site and reloads the browser when a file changes. build writes the site to dist. A build fails on an unknown config key, an unknown layout, or two files that write the same path.

Publish to GitHub Pages

Build in a workflow and upload dist with actions/upload-pages-artifact, then deploy it with actions/deploy-pages. Set the repository's Pages source to GitHub Actions. This site is built that way: see .github/workflows/deploy-site.yml in the repository.