github.com/zserge/zs@v0.0.0-20200324061937-4900afa45db4/README.md (about)

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