mirror of
https://git.mills.io/prologic/zs.git
synced 2024-11-03 01:38:30 -04:00
250 lines
6.6 KiB
Markdown
250 lines
6.6 KiB
Markdown
# zs - Zen Static site generator
|
|
|
|
zs is an extremely minimal static site generator written in Go.
|
|
|
|
[](https://ci.mills.io/prologic/zs)
|
|
|
|
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)
|
|
* [Frequently Asked Questions](#frequently-asked-questions)
|
|
* [How do I link to other pages?](#how-do-i-link-to-other-pages)
|
|
* [License](#license)
|
|
|
|
<!-- tocstop -->
|
|
|
|
## 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).
|
|
|
|
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.
|
|
|
|
## License
|
|
|
|
`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). |