Update README

This commit is contained in:
James Mills 2023-03-26 12:47:07 +10:00
parent 40d6f8312a
commit a1308368b3
No known key found for this signature in database
GPG Key ID: AC4C014F1440EBD6

View File

@ -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).
### Extension: Include
Here are some example plugins you might find useful in your site.
### 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]