2023-03-11 23:13:53 -05:00
# zs - Zen Static site generator
2015-04-10 08:11:37 -04:00
2014-12-05 16:49:42 -05:00
zs is an extremely minimal static site generator written in Go.
2023-03-11 23:13:53 -05:00
[](https://ci.mills.io/prologic/zs)
2014-12-05 16:49:42 -05:00
2023-03-12 04:04:55 -04:00
## 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
```
2014-12-05 16:49:42 -05:00
## Features
* Zero configuration (no configuration file needed)
* Cross-platform
* Highly extensible
2015-09-02 17:21:50 -04:00
* Works well for blogs and generic static websites (landing pages etc)
2014-12-05 16:49:42 -05:00
* Easy to learn
* Fast
## Installation
2023-03-11 23:13:53 -05:00
Download the binaries from [go.mills.io/prologic/zs ](https://git.mills.io/prologic/zs ):
```console
go get go.mills.io/zs@latest
```
2014-12-05 16:49:42 -05:00
2023-03-12 04:04:55 -04:00
Or build from source manually:
2023-03-11 23:13:53 -05:00
```console
git clone https://git.mills.io/prologic/zs
cd zs
make install
```
2014-12-05 16:49:42 -05:00
## Ideology
2021-09-17 19:32:14 -04:00
Keep your texts in markdown, or HTML format right in the main directory
2015-09-02 17:21:50 -04:00
of your blog/site.
2014-12-05 16:49:42 -05:00
Keep all service files (extensions, layout pages, deployment scripts etc)
in the `.zs` subdirectory.
2023-03-11 23:13:53 -05:00
Define variables in the header of the content files using [YAML front matter ](https://assemble.io/docs/YAML-front-matter.html ):
2014-12-05 16:49:42 -05:00
2023-03-11 23:13:53 -05:00
```markdown
---
title: My web site
keywords: best website, hello, world
---
2014-12-05 16:49:42 -05:00
2023-03-11 23:13:53 -05:00
Markdown text goes after a header *separator*
```
2014-12-05 16:49:42 -05:00
Use placeholders for variables and plugins in your markdown or html
2015-09-02 17:21:50 -04:00
files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}.
2014-12-05 16:49:42 -05:00
Write extensions in any language you like and put them into the `.zs`
2023-03-12 04:04:55 -04:00
sub-directory.
2014-12-05 16:49:42 -05:00
Everything the extensions prints to stdout becomes the value of the
placeholder.
2015-09-02 17:21:50 -04:00
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:
2014-12-05 16:49:42 -05:00
2023-03-11 23:13:53 -05:00
- `$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
2014-12-05 16:49:42 -05:00
2023-03-12 04:04:55 -04:00
## 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 }}
```
2014-12-05 16:49:42 -05:00
2023-03-12 04:04:55 -04:00
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` :
2015-09-02 17:21:50 -04:00
2023-03-11 23:13:53 -05:00
```bash
2023-03-12 04:04:55 -04:00
#!/bin/sh
2015-09-02 17:21:50 -04:00
for f in ./blog/*.md ; do
2023-03-12 04:04:55 -04:00
d="$("$ZS" var "$f" date)"
2015-09-02 17:21:50 -04:00
if [ ! -z $d ] ; then
2023-03-12 04:04:55 -04:00
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)"
2015-09-02 17:21:50 -04:00
echo $timestamp \
"< item > " \
"< title > $title< / title > " \
"< link > http://zserge.com/$url< / link > " \
2023-03-12 04:04:55 -04:00
"< description > $desc< / description > " \
2015-09-02 17:21:50 -04:00
"< pubDate > $(date --date @$timestamp -R)< / pubDate > " \
"< guid > http://zserge.com/$url< / guid > " \
"< / item > "
fi
done | sort -r -n | cut -d' ' -f2-
```
2014-12-05 16:49:42 -05:00
## Hooks
There are two special plugin names that are executed every time the build
2023-03-12 04:04:55 -04:00
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` :
2014-12-05 16:49:42 -05:00
2023-03-11 23:13:53 -05:00
```bash
#!/bin/sh
2014-12-05 16:49:42 -05:00
2023-03-11 23:13:53 -05:00
set -e
2014-12-05 16:49:42 -05:00
2023-03-11 23:13:53 -05:00
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"
2014-12-05 16:49:42 -05:00
2023-03-11 23:13:53 -05:00
rm -rf "$ZS_OUTDIR/css/fa.css"
rm -rf "$ZS_OUTDIR/css/screen.css"
```
2015-09-02 17:21:50 -04:00
2023-03-11 23:13:53 -05:00
## Command line usage
2014-12-05 16:49:42 -05:00
2023-03-11 23:13:53 -05:00
- `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.
2023-03-12 04:04:55 -04:00
- `zs serve` rebuilds your site and serve it on the network.
2023-03-11 23:13:53 -05:00
- `zs var <filename> [var1 var2...]` prints a list of variables defined in the
2014-12-05 16:49:42 -05:00
header of a given markdown file, or the values of certain variables (even if
it's an empty string).
## License
2023-03-12 04:04:55 -04:00
`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 ).
