From f421e30ba84b69cbb804db3574467e90598e401f Mon Sep 17 00:00:00 2001 From: James Mills <1290234+prologic@users.noreply.github.com> Date: Sun, 26 Mar 2023 13:36:55 +1000 Subject: [PATCH] Fix README and document extensions and configuration file --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 663ac07..d3fbe57 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ Table of Contents: * [Ideology](#ideology) * [Configuration](#configuration) * [Configuration file](#configuration-file) + * [Extensions (Markdown)](#extensions-markdown) + * [Plugins](#plugins) * [Include](#include) * [RSS](#rss) * [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: ```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 @@ -155,11 +182,6 @@ Here are some example plugins you might find useful in your site. ```bash #!/bin/sh -if [ ! $# = 1 ]; then - printf "Usage: %s \n" "$(basename "$0")" - exit 0 -fi - if [ -f "$1" ]; then cat "$1" else @@ -208,13 +230,8 @@ You can use these to customize the build before and after. For example you can u ```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 @@ -234,11 +251,11 @@ $ 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. + - 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 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. + - 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] @@ -252,9 +269,15 @@ Available Commands: 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 + -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. ``` @@ -268,3 +291,13 @@ Easy! Just write a normal HTML link using an `title` t ## 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 \ No newline at end of file