4.6 KiB
zs - Zen Static site generator
zs is an extremely minimal static site generator written in Go.
Quick Start
go get install go.mills.io/zs@latest
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
Features
- Zero configuration (no configuration file needed)
- Cross-platform
- Highly extensible
- Works well for blogs and generic static websites (landing pages etc)
- Easy to learn
- Fast
Installation
Download the binaries from go.mills.io/prologic/zs:
go get 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
Extensions
Extensions are just executables in any language that output content. They can be system executables like data or custom extensions that you place in .zs/. To use an extensions 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
Extensions can be written in any language you know (Bash, Python, Lua, JavaScript, Go, even Assembler). Here are some example extensions you might find useful in your site.
Extension: Include
.zs/include:
#!/bin/sh
if [ ! $# = 1 ]; then
printf "Usage: %s <file>\n" "$(basename "$0")"
exit 0
fi
if [ -f "$1" ]; then
cat "$1"
else
echo "error: file not found $1"
fi
Extension: 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-
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 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
set -e
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"
rm -rf "$ZS_OUTDIR/css/fa.css"
rm -rf "$ZS_OUTDIR/css/screen.css"
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).
License
zs is licensed under the terms of the MIT License and was orignally forked from zserge/zs also licensed under the terms of the MIT License.