Fix README and document extensions and configuration file

This commit is contained in:
James Mills 2023-03-26 13:36:55 +10:00
parent 320cc026ee
commit f421e30ba8
No known key found for this signature in database
GPG Key ID: AC4C014F1440EBD6

View File

@ -14,6 +14,8 @@ Table of Contents:
* [Ideology](#ideology) * [Ideology](#ideology)
* [Configuration](#configuration) * [Configuration](#configuration)
* [Configuration file](#configuration-file) * [Configuration file](#configuration-file)
* [Extensions (Markdown)](#extensions-markdown)
* [Plugins](#plugins)
* [Include](#include) * [Include](#include)
* [RSS](#rss) * [RSS](#rss)
* [Hooks](#hooks) * [Hooks](#hooks)
@ -125,6 +127,31 @@ By default no configuration is required. Variables can be defined at the top of
The basic structure of a configuration file looks like: The basic structure of a configuration file looks like:
```yaml ```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
@ -155,11 +182,6 @@ Here are some example plugins you might find useful in your site.
```bash ```bash
#!/bin/sh #!/bin/sh
if [ ! $# = 1 ]; then
printf "Usage: %s <file>\n" "$(basename "$0")"
exit 0
fi
if [ -f "$1" ]; then if [ -f "$1" ]; then
cat "$1" cat "$1"
else else
@ -208,13 +230,8 @@ You can use these to customize the build before and after. For example you can u
```bash ```bash
#!/bin/sh #!/bin/sh
set -e
minify -o "$ZS_OUTDIR/css/fa.min.css" "$ZS_OUTDIR/css/fa.css" 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" 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 ## Command line usage
@ -234,11 +251,11 @@ $ zs --help
zs is an extremely minimal static site generator written in Go. 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 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. - 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: - 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 }}. - 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. - Write extensions 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. - Everything the extensions prints to stdout becomes the value of the placeholder.
Usage: Usage:
zs [command] zs [command]
@ -252,9 +269,15 @@ Available Commands:
watch Watches for file changes and rebuilds modified files watch Watches for file changes and rebuilds modified files
Flags: Flags:
-d, --debug Enable debug logging -c, --config string config file (default: .zs/config.yml)
-h, --help help for zs -D, --debug enable debug logging $($ZS_DEBUG)
-v, --version version for zs -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. Use "zs [command] --help" for more information about a command.
``` ```
@ -268,3 +291,13 @@ Easy! Just write a normal HTML link using an `<a href="/other.html">title</a>` t
## License ## 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). `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