mirror of https://git.mills.io/prologic/zs.git
Fix README and document extensions and configuration file
This commit is contained in:
James Mills
parent
320cc026ee
commit
f421e30ba8
65
README.md
65
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
|
||||
Loading…
Reference in New Issue