️ an extremely minimal static site generator written in Go.
Go to file
2023-03-18 17:40:46 +10:00
.dockerfiles Refactor a bunch of stuff adding zs serve, CI/CD workflows, fixing docs and license (#10) 2023-03-12 04:13:53 +00:00
contrib Cleanup 2023-03-12 20:28:29 +10:00
testdata Fix tests 2023-03-18 17:40:46 +10:00
tools Add release script 2021-09-18 09:43:22 +10:00
.drone.yml Fix Drone CI config to publis to prologic/zs (not prologic/saltyim) 2023-03-12 14:33:46 +10:00
.gitignore Add more tests 2023-03-12 21:23:22 +10:00
.goreleaser.yml Add release script 2021-09-18 09:43:22 +10:00
build_test.go Forked project 2021-09-18 09:32:14 +10:00
Dockerfile Add -p flag to Docker image's runtime CMD 2023-03-18 13:07:23 +10:00
go.mod Add additional goldmark extensions (#14) 2023-03-18 07:23:10 +00:00
go.sum Add additional goldmark extensions (#14) 2023-03-18 07:23:10 +00:00
LICENSE Refactor a bunch of stuff adding zs serve, CI/CD workflows, fixing docs and license (#10) 2023-03-12 04:13:53 +00:00
LICENSE.old Refactor a bunch of stuff adding zs serve, CI/CD workflows, fixing docs and license (#10) 2023-03-12 04:13:53 +00:00
main_test.go Code cleanup 2021-10-29 02:10:15 +10:00
main.go Fix tests 2023-03-18 17:40:46 +10:00
Makefile Move tools to a tools layer 2023-03-16 19:22:56 +10:00
preflight.sh Refactor a bunch of stuff adding zs serve, CI/CD workflows, fixing docs and license (#10) 2023-03-12 04:13:53 +00:00
README.md Update README's TOC 2023-03-16 19:08:10 +10:00
version.go Add a better set of cli commands using cobra/pflag and add version and help to all commands 2023-03-12 16:34:38 +10:00

zs - Zen Static site generator

zs is an extremely minimal static site generator written in Go.

Build Status

Table of Contents:

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 the zs executable
  • $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 build
  • posthook -- 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 build re-builds your site.
  • zs build <file> re-builds one file and prints resulting content to stdout.
  • zs watch rebuilds your site every time you modify any file.
  • zs serve rebuilds 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:
  -d, --debug     Enable debug logging
  -h, --help      help for zs
  -v, --version   version for zs

Use "zs [command] --help" for more information about a command.

Frequently Asked Questions

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.