mirror of
https://git.mills.io/prologic/zs.git
synced 2024-11-17 17:56:11 -05:00
Add better README, docs and examples of using extensions (Fixes #1)
This commit is contained in:
James Mills
parent
7198656bcd
commit
89db15666a
99
README.md
99
README.md
@ -4,6 +4,30 @@ zs is an extremely minimal static site generator written in Go.
|
||||
|
||||
[](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
|
||||
|
||||
* 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
|
||||
```
|
||||
|
||||
Or build from source manaully:
|
||||
Or build from source manually:
|
||||
|
||||
```console
|
||||
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 }}.
|
||||
|
||||
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
|
||||
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_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
|
||||
#!/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)
|
||||
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`
|
||||
descr=`$ZS var $f description`
|
||||
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>$descr</description>" \
|
||||
"<description>$desc</description>" \
|
||||
"<pubDate>$(date --date @$timestamp -R)</pubDate>" \
|
||||
"<guid>http://zserge.com/$url</guid>" \
|
||||
"</item>"
|
||||
@ -91,8 +157,14 @@ done | sort -r -n | cut -d' ' -f2-
|
||||
## Hooks
|
||||
|
||||
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
|
||||
content generation, or additional commands, like to minify CSS or Javascript files.
|
||||
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
|
||||
@ -111,10 +183,11 @@ rm -rf "$ZS_OUTDIR/css/screen.css"
|
||||
- `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).
|
||||
|
||||
## License
|
||||
|
||||
`zs` is licensed under the terms of the [MIT License](/LICENSE) and was orignally forked from [zserge/zs](https://github.com/zserge/zs) also licensed under the terms of the [MIT License](/LICENSE.old).
|
||||
`zs` is licensed under the terms of the [MIT License](/LICENSE) and was orignally forked from [zserge/zs](https://github.com/zserge/zs) also licensed under the terms of the [MIT License](/LICENSE.old).
|
||||
Loading…
Reference in New Issue
Block a user