zs - ⚡️ Zen Static site generator
zs is an extremely minimal static site generator written in Go.
Table of Contents:
Quick Start
go install go.mills.io/zs@latest
mkdir .zs && cat > .zs/layout.html <<EOF
<html>
<head>
<title>{{ title }}</title>
</head>
<body>{{ content }}</body>
</html>
EOF
cat > index.md <<EOF
---
title: Hello World
---
# Hello World
Hello World!
EOF
zs serve
For a starter template see the zs-starter-template which can also be found running live at zs.mills.io.
Features
- Zero configuration (optional configuration file)
- Highly configurable (flags, env vars, configuration file)
- Cross-platform (macOS, Windows, Linux)
- Highly extensible via plugins in any language
- Works well for blogs and generic static websites (landing pages, etc)
- Easy to learn
- Fast!
- Routes file (
.routes) for redirects, rewrites, and error handling
Installation
Download the binaries from go.mills.io/prologic/zs:
go install go.mills.io/zs@latest
Or build from source manually:
git clone https://git.mills.io/prologic/zs
cd zs
make install
Ideology
Keep your texts in markdown, or HTML format right in the main directory of your blog/site.
Keep all service files (extensions, layout pages, deployment scripts etc)
in the .zs subdirectory.
Define variables in the header of the content files using YAML front matter:
---
title: My web site
keywords: best website, hello, world
---
Markdown text goes after a header *separator*
Use placeholders for variables and plugins in your markdown or html
files, e.g. {{ title }} or {{ command arg1 arg2 }}.
Write extensions in any language you like and put them into the .zs
sub-directory.
Everything the extensions prints to stdout becomes the value of the placeholder.
Every variable from the content header will be passed via environment variables like title becomes $ZS_TITLE and so on. There are some special variables:
$ZS- a path to thezsexecutable$ZS_OUTDIR- a path to the directory with generated files$ZS_FILE- a path to the currently processed markdown file$ZS_URL- a URL for the currently generated page
Configuration
By default no configuration is required. Variables can be defined at the top of each content page using YAML front-matter as described in Idealogy. As your site gets more complex, you may want to define a site-level configuration file. There are a couple of ways to do this:
- Using command-line flags of
zsitself, seezs --helpfor configuration options. - Using environment variables such as
ZS_PRODUCTION=1. These match the command-line flags above, are uppercase and prefixed withZS_. - Using
zs -c/--config ...to pass an explicit configuration file. - Placing a
.zs/config.ymlconfiguration file in your.zsdirectory.
Configuration file
The basic structure of a configuration file looks like:
---
title: zs starter template
description: A starter template for the Zen Static (zs) site generator
keywords: zen, static, zs, starter, template, site, website, template, generator, ssg
extensions:
- typography
- wikilink
- fences
- embed
- d2
Extensions (Markdown)
zs supports content written in Markdown, index.md for example and uses the Goldmark Markdown parser with a number of extensions enabled by default:
- anchor -- Adds anchors (permalinks) next to all headers in a document.
- d2 -- Adds support for D2 diagrams.
- embed -- Adds support for rendering embeds from YouTube links.
- fences -- Support for pandoc-style fenced divs.
- highlighting -- Adds support for syntax highlighting of code.
- wikilink -- Adds support for wiki-style links to goldmark.
For a full-list of default extensions enabled, see zs --help and the -e/--extensions flag.
Plugins
Plugins are just executables in any language that output content. They can be system executables like data or custom scripts or programs that you place in .zs/. To use a plugins simply reference it in your content like so:
Site last updated at {{ date }}
or:
Here's a list of support features:
{{ features }}
Where features is a script defined in .zs/features
Plugins can be written in any language you know (Bash, Python, Lua, JavaScript, Go, even Assembler).
Here are some example plugins you might find useful in your site.
Include
.zs/include:
#!/bin/sh
if [ -f "$1" ]; then
cat "$1"
else
echo "error: file not found $1"
fi
RSS
.zs/rss:
#!/bin/sh
for f in ./blog/*.md ; do
d="$("$ZS" var "$f" date)"
if [ ! -z $d ] ; then
timestamp="$(date --date "$d" +%s)"
url="$("$ZS" var "$f" url)"
title="$($ZS var "$f" title | tr A-Z a-z)"
desc="$($ZS var "$f" description)"
echo $timestamp \
"<item>" \
"<title>$title</title>" \
"<link>http://zserge.com/$url</link>" \
"<description>$desc</description>" \
"<pubDate>$(date --date @$timestamp -R)</pubDate>" \
"<guid>http://zserge.com/$url</guid>" \
"</item>"
fi
done | sort -r -n | cut -d' ' -f2-
Looking for more plugins? Check out the contrib/plugins collection!
Hooks
There are two special plugin names that are executed every time the build happens:
prehook-- executed before the buildposthook-- executed after the build
You must have prehook for posthook to work correctly, and posthook will only run if a file has been modified.
You can use these to customize the build before and after. For example you can use the posthook to minify CSS or Javascript files.
.zs/posthook:
#!/bin/sh
minify -o "$ZS_OUTDIR/css/fa.min.css" "$ZS_OUTDIR/css/fa.css"
minify -o "$ZS_OUTDIR/css/site.min.css" "$ZS_OUTDIR/css/site.css"
Looking for more hooks? Check out the contrib/hooks collection!
Routes
zs supports a .routes file for simple request routing. This lets you configure redirects, rewrites, and error responses directly within your static site.
Syntax
Each line in .routes has the form:
<pattern> <target> [status]
<pattern>— A URL path or glob to match (e.g./old,/blog/*)<target>— Destination path or URL[status](optional) — HTTP status code. Defaults to302(temporary redirect).
Examples
Redirects
/old-about /about 301
/blog/* /posts/$1 302
- Requests to
/old-aboutbecome/aboutwith a permanent 301. - Requests to
/blog/somethingbecome/posts/somethingwith a temporary 302.
Rewrites
/docs/* /assets/docs/$1 200
This serves files from /assets/docs/ while keeping the URL under /docs/.
Custom error / gone
/secret /404.html 404
/old-page - 410
/secretalways serves your custom 404 page./old-pageresponds with 410 Gone (no body).
⚡️ Useful for migrations, vanity URLs, or serving legacy paths without a reverse proxy.
Index
zs supports indexing documents and providing a query command for quickly
retrieving documents or metadata on documents quickly and easily without having
to spend time walking directory trees and parses files over and over again.
Building the index
zs index -r . -i "posts/*.md" -i "pages/*.md" -e ".cache/*" -o .cache/zs/index.json
Flags:
-r, --rootRoot directory to index (default.).-i, --includeGlob include patterns (repeatable). If omitted, all parsable content files are considered.-e, --excludeGlob exclude patterns (repeatable).-o, --outOutput index path (default.cache/zs/index.json).
Querying the index
- Extract variables from a document (front matter + defaults):
zs query vars posts/2025-01-02-hello.md
- Find neighbors (prev/next in chronological order within the same directory) using the on-disk index:
zs query neighbors posts/2025-01-02-hello.md -o .cache/zs/index.json
- List posts by tag / year / month:
zs query list --tag go --year 2025 --month 9
The on-disk index is a single JSON file containing an array of records with path, url, title, date, vars, tags, and neighbors.
Command line usage
zs buildre-builds your site.zs build <file>re-builds one file and prints resulting content to stdout.zs watchrebuilds your site every time you modify any file.zs serverebuilds your site and serve it on the network.zs var <filename> [var1 var2...]prints a list of variables defined in the header of a given markdown file, or the values of certain variables (even if it's an empty string).
For full usage see zs --help:
$ zs --help
zs is an extremely minimal static site generator written in Go.
- Keep your texts in markdown, or HTML format right in the main directory of your blog/site.
- Keep all service files (extensions, layout pages, deployment scripts etc) in the .zs subdirectory.
- Define variables in the header of the content files using YAML front matter:
- Use placeholders for variables and plugins in your markdown or html files, e.g. {{ title }} or {{ command arg1 arg2 }}.
- Write extensions in any language you like and put them into the .zs sub-directory.
- Everything the extensions prints to stdout becomes the value of the placeholder.
Usage:
zs [command]
Available Commands:
build Builds the whole site or a single file
completion Generate the autocompletion script for the specified shell
help Help about any command
serve Serves the site and rebuilds automatically
var Display variables for the specified file
watch Watches for file changes and rebuilds modified files
Flags:
-c, --config string config file (default: .zs/config.yml)
-D, --debug enable debug logging $($ZS_DEBUG)
-d, --description string site description ($ZS_DESCRIPTION)
-e, --extensions strings override and enable specific extensions (default [table,linkify,highlighting,fences,footnote,cjk,d2,embed,wikilink,tasklist,definitionlist,anchor,strikethrough,typography])
-h, --help help for zs
-k, --keywords string site keywords ($ZS_KEYWORDS)
-p, --production enable production mode ($ZS_PRODUCTION)
-t, --title string site title ($ZS_TITLE)
-v, --version version for zs
Use "zs [command] --help" for more information about a command.
zs Users
Here's a few sites that use zs today:
- https://yarn.social -- Landing page of the decentralized microBlogging ecosystem.
- https://salty.im -- Landing page of the e2e encrypted IndieWeb inspired messaging protocol.
- https://zs.mills.io -- zs starter template demo.
- https://prologic.shortcircuit.net.au -- Home page of James Mills / prologic (author of zs)
Want to add your site here? File an issue or submit a pull-request!
Frequently Asked Questions
How do I link to other pages?
Easy! Just write a normal HTML link using an <a href="/other.html">title</a> tag or a Markdown link using the normal [title](/other.html) syntax.
License
zs is licensed under the terms of the MIT License and was originally forked from zserge/zs also licensed under the terms of the MIT License.