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-16 05:07:18 -04:00
Table of Contents:
<!-- toc -->
- [zs - Zen Static site generator ](#zs---zen-static-site-generator )
* [Quick Start ](#quick-start )
* [Features ](#features )
* [Installation ](#installation )
* [Ideology ](#ideology )
* [Extensions ](#extensions )
* [Extension: Include ](#extension-include )
* [Extension: RSS ](#extension-rss )
* [Hooks ](#hooks )
* [Command line usage ](#command-line-usage )
2023-03-16 05:08:10 -04:00
* [Frequently Asked Questions ](#frequently-asked-questions )
* [How do I link to other pages? ](#how-do-i-link-to-other-pages )
2023-03-16 05:07:18 -04:00
* [License ](#license )
<!-- tocstop -->
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
```
2023-03-18 06:31:34 -04:00
For a starter template see the [zs-starter-tempate ](https://git.mills.io/prologic/zs-stater-template ) which can also be found running live at [zs.mills.io ](https://zs.mills.io ).
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).
2023-03-16 05:07:18 -04:00
For full usage see `zs --help` :
```console
$ 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
### 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.
2014-12-05 16:49:42 -05:00
## License
2023-03-18 06:31:34 -04:00
`zs` is licensed under the terms of the [MIT License ](/LICENSE ) and was originally forked from [zserge/zs ](https://github.com/zserge/zs ) also licensed under the terms of the [MIT License ](/LICENSE.old ).
