Changeset 39 in code

Timestamp:

Sep 2, 2015, 9:21:50 PM (10 years ago)

Author:

zaitsev.serge

Message:

updated README

File:

• trunk/README.md (modified) (6 diffs)

trunk/README.md

@@ -15 +15 @@
 * Cross-platform
 * Highly extensible
+* Works well for blogs and generic static websites (landing pages etc)
 * Easy to learn
 * Fast
@@ -26 +27 @@
 ## Ideology
 
-Keep your texts in markdown format in the root directory of your blog/site.
+Keep your texts in markdown, [amber] 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.
 
-Define variables in the header of the markdown files:
+Define variables in the header of the content files using [YAML]:
 
         title: My web site
         keywords: best website, hello, world
+        ---
 
-        Markdown text goes after a *newline*
+        Markdown text goes after a header *separator*
 
 Use placeholders for variables and plugins in your markdown or html
-files, e.g. `{{ title }}`.
+files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}.
 
 Write extensions in any language you like and put them into the `.zs`
@@ -47 +50 @@
 placeholder.
 
-Extensions can use special environment variables, like:
+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:
 
 * `$ZS` - a path to the `zs` executable
@@ -54 +57 @@
 * `$ZS_URL` - a URL for the currently generated page
 
-You can also pass command line arguments, e.g: `{{ my-plugin arg1 arg2 }}`
+## Example of RSS generation
 
-## Example of RSS generation
+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:
+
+``` bash
+for f in ./blog/*.md ; do
+        d=$($ZS var $f date)
+        if [ ! -z $d ] ; then
+                timestamp=`date --date "$d" +%s`
+                url=`$ZS var $f url`
+                title=`$ZS var $f title | tr A-Z a-z`
+                descr=`$ZS var $f description`
+                echo $timestamp \
+                        "<item>" \
+                        "<title>$title</title>" \
+                        "<link>http://zserge.com/$url</link>" \
+                        "<description>$descr</description>" \
+                        "<pubDate>$(date --date @$timestamp -R)</pubDate>" \
+                        "<guid>http://zserge.com/$url</guid>" \
+                "</item>"
+        fi
+done | sort -r -n | cut -d' ' -f2-
+```
 
 ## Hooks
 
 There are two special plugin names that are executed every time the build
-happens - `pre` and `post`. You can define some global action here like compile
-your LESS to CSS etc:
+happens - `prehook` and `posthook`. You can define some global actions here like
+content generation, or additional commands, like LESS to CSS conversion:
 
         # .zs/post
@@ -70 +93 @@
         rm -f $ZS_OUTDIR/styles.css
 
+## Syntax sugar
+
+By default, `zs` converts each `.amber` file into `.html`, so you can use lightweight Jade-like syntax instead of bloated HTML.
+
+Also, `zs` converts `.gcss` into `.css`, so you don't really need LESS or SASS. More about GCSS can be found [here][gcss].
+
 ## Command line usage
 
 `zs build` re-builds your site.
+
+`zs build <file>` re-builds one file and prints resulting content to stdout.
 
 `zs watch` rebuilds your site every time you modify any file.
@@ -83 +114 @@
 
 The software is distributed under the MIT license.
+
+[amber]: https://github.com/eknkc/amber/
+[YAML]: https://github.com/go-yaml/yaml
+[gcss]: https://github.com/yosssi/gcss