mirror/zs
1
0
Fork 0
mirror of https://git.mills.io/prologic/zs synced 2024-11-22 13:26:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

Add better README, docs and examples of using extensions (Fixes #1)

Browse Source
This commit is contained in:
James Mills 2023-03-12 18:04:55 +10:00
parent 7198656bcd
commit 89db15666a
No known key found for this signature in database
GPG Key ID: AC4C014F1440EBD6
1 changed files with 86 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
README.md
View File

@ -4,6 +4,30 @@ zs is an extremely minimal static site generator written in Go.
[![Build Status](https://ci.mills.io/api/badges/prologic/zs/status.svg)](https://ci.mills.io/prologic/zs) [![Build Status](https://ci.mills.io/api/badges/prologic/zs/status.svg)](https://ci.mills.io/prologic/zs)
## 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 ## Features
* Zero configuration (no configuration file needed) * Zero configuration (no configuration file needed)
@ -21,7 +45,7 @@ Download the binaries from [go.mills.io/prologic/zs](https://git.mills.io/prolog
go get go.mills.io/zs@latest go get go.mills.io/zs@latest
``` ```
Or build from source manaully: Or build from source manually:
```console ```console
git clone https://git.mills.io/prologic/zs git clone https://git.mills.io/prologic/zs
@ -52,7 +76,7 @@ Use placeholders for variables and plugins in your markdown or html
files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}. files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}.
Write extensions in any language you like and put them into the `.zs` Write extensions in any language you like and put them into the `.zs`
subdiretory. sub-directory.
Everything the extensions prints to stdout becomes the value of the Everything the extensions prints to stdout becomes the value of the
placeholder. placeholder.
@ -64,23 +88,65 @@ Every variable from the content header will be passed via environment variables
- `$ZS_FILE` - a path to the currently processed markdown file - `$ZS_FILE` - a path to the currently processed markdown file
- `$ZS_URL` - a URL for the currently generated page - `$ZS_URL` - a URL for the currently generated page
## Example of RSS generation ## Extensions
Extensions can be written in any language you know (Bash, Python, Lua, JavaScript, Go, even Assembler). Here's an example of how to scan all markdown blog posts and create RSS items: 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 ```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 for f in ./blog/*.md ; do
d=$($ZS var $f date) d="$("$ZS" var "$f" date)"
if [ ! -z $d ] ; then if [ ! -z $d ] ; then
timestamp=`date --date "$d" +%s` timestamp="$(date --date "$d" +%s)"
url=`$ZS var $f url` url="$("$ZS" var "$f" url)"
title=`$ZS var $f title | tr A-Z a-z` title="$("$ZS" var "$f" title | tr A-Z a-z)"
descr=`$ZS var $f description` desc="$("$ZS" var "$f" description)"
echo $timestamp \ echo $timestamp \
"<item>" \ "<item>" \
"<title>$title</title>" \ "<title>$title</title>" \
"<link>http://zserge.com/$url</link>" \ "<link>http://zserge.com/$url</link>" \
"<description>$descr</description>" \ "<description>$desc</description>" \
"<pubDate>$(date --date @$timestamp -R)</pubDate>" \ "<pubDate>$(date --date @$timestamp -R)</pubDate>" \
"<guid>http://zserge.com/$url</guid>" \ "<guid>http://zserge.com/$url</guid>" \
"</item>" "</item>"
@ -91,8 +157,14 @@ done | sort -r -n | cut -d' ' -f2-
## Hooks ## Hooks
There are two special plugin names that are executed every time the build There are two special plugin names that are executed every time the build
happens - `prehook` and `posthook`. You can define some global actions here like happens:
content generation, or additional commands, like to minify CSS or Javascript files.
- `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 ```bash
#!/bin/sh #!/bin/sh
@ -111,6 +183,7 @@ rm -rf "$ZS_OUTDIR/css/screen.css"
- `zs build` re-builds your site. - `zs build` re-builds your site.
- `zs build <file>` re-builds one file and prints resulting content to stdout. - `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 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 - `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 header of a given markdown file, or the values of certain variables (even if
it's an empty string). it's an empty string).