mirror of
https://git.mills.io/prologic/zs
synced 2024-11-22 05:16:11 +03:00
271 lines
7.6 KiB
Markdown
271 lines
7.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)
|
|
* [Configuration](#configuration)
|
|
* [Configuration file](#configuration-file)
|
|
* [Include](#include)
|
|
* [RSS](#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
|
|
```
|
|
|
|
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).
|
|
|
|
## Features
|
|
|
|
- Zero configuration (optional configuration file)
|
|
- Highly configurable (flags, env vars, configuration file)
|
|
- Cross-platform (macOS, Windows, Linux)
|
|
- Highly extensible via plugins in any language
|
|
- 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
|
|
|
|
## Configuration
|
|
|
|
By default no configuration is required. Variables can be defined at the top of each content page using YAML front-matter as described in [Idealogy](#ideology). As your site gets more complex, you _may_ want to define a site-level configuration file. There are a couple of ways to do this:
|
|
|
|
- Using command-line flags of `zs` itself, see `zs --help` for configuration options.
|
|
- Using environment variables such as `ZS_PRODUCTION=1`. These match the command-line flags above, are uppercase and prefixed with `ZS_`.
|
|
- Using `zs -c/--config ...` to pass an explicit configuration file.
|
|
- Placing a `.zs/config.yml` configuration file in your `.zs` directory.
|
|
|
|
### Configuration file
|
|
|
|
The basic structure of a configuration file looks like:
|
|
|
|
```yaml
|
|
|
|
## Plugins
|
|
|
|
Plugins are just executables in any language that output content. They can be system executables like `data` or custom scripts or programs that you place in `.zs/`. To use a plugins 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`
|
|
|
|
Plugins can be written in any language you know (Bash, Python, Lua, JavaScript, Go, even Assembler).
|
|
|
|
Here are some example plugins you might find useful in your site.
|
|
|
|
### 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
|
|
```
|
|
|
|
### 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 (plugins, 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 plugins in any language you like and put them into the .zs sub-directory.
|
|
- Everything the plugin 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).
|