From: James Mills <1290234+prologic@users.noreply.github.com>
Date: Sun, 26 Mar 2023 03:36:55 +0000 (+1000)
Subject: Fix README and document extensions and configuration file
X-Git-Tag: 0.3.0
X-Git-Url: http://10.10.0.4:5575/?a=commitdiff_plain;h=8e30918ce08de250f13730354a2a62ae908ab054;p=aya.git

Fix README and document extensions and configuration file
---

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 <file>\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 `<a href="/other.html">title</a>` 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