zs/README.md

193 lines
4.6 KiB
Markdown

# zs - Zen Static site generator
zs is an extremely minimal static site generator written in Go.
[![Build Status](https://ci.mills.io/api/badges/prologic/zs/status.svg)](https://ci.mills.io/prologic/zs)
## Quick Start
```console
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](https://git.mills.io/prologic/zs):
```console
go get go.mills.io/zs@latest
```
Or build from source manually:
```console
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](https://assemble.io/docs/YAML-front-matter.html):
```markdown
---
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:
```markdown
Site last updated at {{{ date }}
```
Or:
```markdown
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`:
```bash
#!/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`:
```bash
#!/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`:
```bash
#!/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).
## License
`zs` is licensed under the terms of the [MIT License](/LICENSE) and was orignally forked from [zserge/zs](https://github.com/zserge/zs) also licensed under the terms of the [MIT License](/LICENSE.old).