From: James Mills <1290234+prologic@users.noreply.github.com>
Date: Sun, 26 Mar 2023 02:47:07 +0000 (+1000)
Subject: Update README
X-Git-Tag: 0.3.0~2
X-Git-Url: http://10.10.0.4:5575/?a=commitdiff_plain;h=a1308368b3c95671801ebbd5e89bfc3ea0374420;p=aya.git

Update README
---

diff --git a/README.md b/README.md
index edea924..663ac07 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,10 @@ Table of Contents:
     * [Features](#features)
     * [Installation](#installation)
     * [Ideology](#ideology)
-    * [Extensions](#extensions)
-        * [Extension: Include](#extension-include)
-        * [Extension: RSS](#extension-rss)
+    * [Configuration](#configuration)
+        * [Configuration file](#configuration-file)
+        * [Include](#include)
+        * [RSS](#rss)
     * [Hooks](#hooks)
     * [Command line usage](#command-line-usage)
     * [Frequently Asked Questions](#frequently-asked-questions)
@@ -51,12 +52,13 @@ For a starter template see the [zs-starter-tempate](https://git.mills.io/prologi
 
 ## Features
 
-* Zero configuration (no configuration file needed)
-* Cross-platform
-* Highly extensible
-* Works well for blogs and generic static websites (landing pages etc)
-* Easy to learn
-* Fast
+- Zero configuration (optional configuration file)
+- Highly configurable (flags, env vars, configuration file)
+- Cross-platform (macOS, Windows, Linux)
+- Highly extensible via plugins in any language
+- Works well for blogs and generic static websites (landing pages, etc)
+- Easy to learn
+- Fast!
 
 ## Installation
 
@@ -109,9 +111,24 @@ 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
 
-## Extensions
+## Configuration
 
-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:
+By default no configuration is required. Variables can be defined at the top of each content page using YAML front-matter as described in [Idealogy](#ideology). As your site gets more complex, you _may_ want to define a site-level configuration file. There are a couple of ways to do this:
+
+- Using command-line flags of `zs` itself, see `zs --help` for configuration options.
+- Using environment variables such as `ZS_PRODUCTION=1`. These match the command-line flags above, are uppercase and prefixed with `ZS_`.
+- Using `zs -c/--config ...` to pass an explicit configuration file.
+- Placing a `.zs/config.yml` configuration file in your `.zs` directory.
+
+### Configuration file
+
+The basic structure of a configuration file looks like:
+
+```yaml
+
+## Plugins
+
+Plugins are just executables in any language that output content. They can be system executables like `data` or custom scripts or programs that you place in `.zs/`. To use a plugins simply reference it in your content like so:
 
 ```markdown
 Site last updated at {{{ date }}
@@ -127,10 +144,11 @@ Here's a list of support 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.
+Plugins can be written in any language you know (Bash, Python, Lua, JavaScript, Go, even Assembler).
+
+Here are some example plugins you might find useful in your site.
 
-### Extension: Include
+### Include
 
 `.zs/include`:
 
@@ -149,7 +167,7 @@ else
 fi
 ```
 
-### Extension: RSS
+### RSS
 
 `.zs/rss`:
 
@@ -216,11 +234,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 (extensions, layout pages, deployment scripts etc) in the .zs subdirectory.
+  - Keep all service files (plugins, 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 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.
+  - 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.
 
 Usage:
   zs [command]