git.mills.io/prologic/zs@v0.0.0-20230312034417-0f4623afae54/README.md (about)

     1  # zs
     2  
     3  zs is an extremely minimal static site generator written in Go.
     4  
     5  It's inspired by `zas` generator, but is even more minimal.
     6  
     7  The name stands for 'zen static' as well as it's my initials.
     8  
     9  ## Features
    10  
    11  * Zero configuration (no configuration file needed)
    12  * Cross-platform
    13  * Highly extensible
    14  * Works well for blogs and generic static websites (landing pages etc)
    15  * Easy to learn
    16  * Fast
    17  
    18  ## Installation
    19  
    20  Download the binaries from Github or build it manually:
    21  
    22  	$ go get git.mills.io/prologic/zs
    23  
    24  ## Ideology
    25  
    26  Keep your texts in markdown, or HTML format right in the main directory
    27  of your blog/site.
    28  
    29  Keep all service files (extensions, layout pages, deployment scripts etc)
    30  in the `.zs` subdirectory.
    31  
    32  Define variables in the header of the content files using [YAML]:
    33  
    34  	title: My web site
    35  	keywords: best website, hello, world
    36  	---
    37  
    38  	Markdown text goes after a header *separator*
    39  
    40  Use placeholders for variables and plugins in your markdown or html
    41  files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}.
    42  
    43  Write extensions in any language you like and put them into the `.zs`
    44  subdiretory.
    45  
    46  Everything the extensions prints to stdout becomes the value of the
    47  placeholder.
    48  
    49  Every variable from the content header will be passed via environment variables like `title` becomes `$ZS_TITLE` and so on. There are some special variables:
    50  
    51  * `$ZS` - a path to the `zs` executable
    52  * `$ZS_OUTDIR` - a path to the directory with generated files
    53  * `$ZS_FILE` - a path to the currently processed markdown file
    54  * `$ZS_URL` - a URL for the currently generated page
    55  
    56  ## Example of RSS generation
    57  
    58  Extensions can be written in any language you know (Bash, Python, Lua, JavaScript, Go, even Assembler). Here's an example of how to scan all markdown blog posts and create RSS items:
    59  
    60  ``` bash
    61  for f in ./blog/*.md ; do
    62  	d=$($ZS var $f date)
    63  	if [ ! -z $d ] ; then
    64  		timestamp=`date --date "$d" +%s`
    65  		url=`$ZS var $f url`
    66  		title=`$ZS var $f title | tr A-Z a-z`
    67  		descr=`$ZS var $f description`
    68  		echo $timestamp \
    69  			"<item>" \
    70  			"<title>$title</title>" \
    71  			"<link>http://zserge.com/$url</link>" \
    72  			"<description>$descr</description>" \
    73  			"<pubDate>$(date --date @$timestamp -R)</pubDate>" \
    74  			"<guid>http://zserge.com/$url</guid>" \
    75  		"</item>"
    76  	fi
    77  done | sort -r -n | cut -d' ' -f2-
    78  ```
    79  
    80  ## Hooks
    81  
    82  There are two special plugin names that are executed every time the build
    83  happens - `prehook` and `posthook`. You can define some global actions here like
    84  content generation, or additional commands, like LESS to CSS conversion:
    85  
    86  	# .zs/post
    87  
    88  	#!/bin/sh
    89  	lessc < $ZS_OUTDIR/styles.less > $ZS_OUTDIR/styles.css
    90  	rm -f $ZS_OUTDIR/styles.css
    91  
    92  ## Command line usage
    93  
    94  `zs build` re-builds your site.
    95  
    96  `zs build <file>` re-builds one file and prints resulting content to stdout.
    97  
    98  `zs watch` rebuilds your site every time you modify any file.
    99  
   100  `zs var <filename> [var1 var2...]` prints a list of variables defined in the
   101  header of a given markdown file, or the values of certain variables (even if
   102  it's an empty string).
   103  
   104  ## License
   105  
   106  The software is distributed under the MIT license.