mirror of
https://git.mills.io/prologic/zs
synced 2024-11-21 21:06:10 +03:00
d7c5c48621
Reviewed-on: https://git.mills.io/prologic/zs/pulls/21 Reviewed-by: James Mills <james@mills.io> Co-authored-by: jedahan <jedahan@noreply@mills.io> Co-committed-by: jedahan <jedahan@noreply@mills.io>
321 lines
10 KiB
Markdown
321 lines
10 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)
|
|
* [Extensions (Markdown)](#extensions-markdown)
|
|
* [Plugins](#plugins)
|
|
* [Include](#include)
|
|
* [RSS](#rss)
|
|
* [Hooks](#hooks)
|
|
* [Command line usage](#command-line-usage)
|
|
* [zs Users](#zs-users)
|
|
* [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 install go.mills.io/zs@latest
|
|
mkdir .zs && 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-template](https://git.mills.io/prologic/zs-starter-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 install 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
|
|
---
|
|
title: zs starter template
|
|
description: A starter template for the Zen Static (zs) site generator
|
|
keywords: zen, static, zs, starter, template, site, website, template, generator, ssg
|
|
|
|
extensions:
|
|
- typography
|
|
- wikilink
|
|
- fences
|
|
- embed
|
|
- d2
|
|
```
|
|
|
|
## Extensions (Markdown)
|
|
|
|
`zs` supports content written in Markdown, `index.md` for example and uses the [Goldmark][goldmark] Markdown parser with a number of extensions enabled by default:
|
|
|
|
- [anchor][anchor] -- Adds anchors (permalinks) next to all headers in a document.
|
|
- [d2][d2] -- Adds support for [D2](https://d2lang.com/) diagrams.
|
|
- [embed][embed] -- Adds support for rendering embeds from YouTube links.
|
|
- [fences][fences] -- Support for pandoc-style fenced divs.
|
|
- [highlighting][highlighting] -- Adds support for syntax highlighting of code.
|
|
- [wikilink][wikilink] -- Adds support for [[wiki]]-style links to goldmark.
|
|
|
|
For a full-list of default extensions enabled, see `zs --help` and the `-e/--extensions` flag.
|
|
|
|
## 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 [ -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-
|
|
```
|
|
|
|
Looking for more plugins? Check out the [contrib/plugins](https://git.mills.io/prologic/zs/src/branch/main/contrib/plugins) collection!
|
|
|
|
## 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 must have `prehook` for `posthook` to work correctly, and `posthook` will only run if a file has been modified.
|
|
|
|
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
|
|
|
|
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"
|
|
```
|
|
|
|
Looking for more hooks? Check out the [contrib/hooks](https://git.mills.io/prologic/zs/src/branch/main/contrib/hooks) collection!
|
|
|
|
## 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:
|
|
-c, --config string config file (default: .zs/config.yml)
|
|
-D, --debug enable debug logging $($ZS_DEBUG)
|
|
-d, --description string site description ($ZS_DESCRIPTION)
|
|
-e, --extensions strings override and enable specific extensions (default [table,linkify,highlighting,fences,footnote,cjk,d2,embed,wikilink,tasklist,definitionlist,anchor,strikethrough,typography])
|
|
-h, --help help for zs
|
|
-k, --keywords string site keywords ($ZS_KEYWORDS)
|
|
-p, --production enable production mode ($ZS_PRODUCTION)
|
|
-t, --title string site title ($ZS_TITLE)
|
|
-v, --version version for zs
|
|
|
|
Use "zs [command] --help" for more information about a command.
|
|
```
|
|
|
|
## zs Users
|
|
|
|
Here's a few sites that use `zs` today:
|
|
|
|
- https://yarn.social -- Landing page of the decentralized microBlogging ecosystem.
|
|
- https://salty.im -- Landing page of the e2e encrypted IndieWeb inspired messaging protocol.
|
|
- https://zs.mills.io -- zs starter template demo.
|
|
- https://prologic.shortcircuit.net.au -- Home page of James Mills / prologic (author of zs)
|
|
|
|
Want to add your site here? File an issue or submit a pull-request!
|
|
|
|
## 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).
|
|
|
|
----
|
|
|
|
[goldmark]: https://github.com/yuin/goldmark
|
|
[anchor]: https://github.com/abhinav/goldmark-anchor
|
|
[d2]: https://github.com/FurqanSoftware/goldmark-d2
|
|
[embed]: https://github.com/13rac1/goldmark-embed
|
|
[fences]: https://github.com/stefanfritsch/goldmark-fences
|
|
[highlighting]: https://github.com/yuin/goldmark-highlighting
|
|
[wikilink]: https://github.com/abhinav/goldmark-wikilink
|