Mercurial > yakumo_izuru > aya

comparison README.md @ 38:ea1bcd29a195 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated README
author zaitsev.serge
date Wed, 02 Sep 2015 21:21:50 +0000
parents 7119cca186bf
children 0adadd497d23
comparison
equal deleted inserted replaced
37:253a7e604e17 38:ea1bcd29a195
12 ## Features 12 ## Features
13 13
14 * Zero configuration (no configuration file needed) 14 * Zero configuration (no configuration file needed)
15 * Cross-platform 15 * Cross-platform
16 * Highly extensible 16 * Highly extensible
17 * Works well for blogs and generic static websites (landing pages etc)
17 * Easy to learn 18 * Easy to learn
18 * Fast 19 * Fast
19 20
20 ## Installation 21 ## Installation
21 22
23 24
24 $ go get github.com/zserge/zs 25 $ go get github.com/zserge/zs
25 26
26 ## Ideology 27 ## Ideology
27 28
28 Keep your texts in markdown format in the root directory of your blog/site. 29 Keep your texts in markdown, [amber] or HTML format right in the main directory
30 of your blog/site.
29 31
30 Keep all service files (extensions, layout pages, deployment scripts etc) 32 Keep all service files (extensions, layout pages, deployment scripts etc)
31 in the `.zs` subdirectory. 33 in the `.zs` subdirectory.
32 34
33 Define variables in the header of the markdown files: 35 Define variables in the header of the content files using [YAML]:
34 36
35 title: My web site 37 title: My web site
36 keywords: best website, hello, world 38 keywords: best website, hello, world
39 ---
37 40
38 Markdown text goes after a *newline* 41 Markdown text goes after a header *separator*
39 42
40 Use placeholders for variables and plugins in your markdown or html 43 Use placeholders for variables and plugins in your markdown or html
41 files, e.g. `{{ title }}`. 44 files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}.
42 45
43 Write extensions in any language you like and put them into the `.zs` 46 Write extensions in any language you like and put them into the `.zs`
44 subdiretory. 47 subdiretory.
45 48
46 Everything the extensions prints to stdout becomes the value of the 49 Everything the extensions prints to stdout becomes the value of the
47 placeholder. 50 placeholder.
48 51
49 Extensions can use special environment variables, like: 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:
50 53
51 * `$ZS` - a path to the `zs` executable 54 * `$ZS` - a path to the `zs` executable
52 * `$ZS_OUTDIR` - a path to the directory with generated files 55 * `$ZS_OUTDIR` - a path to the directory with generated files
53 * `$ZS_FILE` - a path to the currently processed markdown file 56 * `$ZS_FILE` - a path to the currently processed markdown file
54 * `$ZS_URL` - a URL for the currently generated page 57 * `$ZS_URL` - a URL for the currently generated page
55 58
56 You can also pass command line arguments, e.g: `{{ my-plugin arg1 arg2 }}` 59 ## Example of RSS generation
57 60
58 ## Example of RSS generation 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 ```
59 82
60 ## Hooks 83 ## Hooks
61 84
62 There are two special plugin names that are executed every time the build 85 There are two special plugin names that are executed every time the build
63 happens - `pre` and `post`. You can define some global action here like compile 86 happens - `prehook` and `posthook`. You can define some global actions here like
64 your LESS to CSS etc: 87 content generation, or additional commands, like LESS to CSS conversion:
65 88
66 # .zs/post 89 # .zs/post
67 90
68 #!/bin/sh 91 #!/bin/sh
69 lessc < $ZS_OUTDIR/styles.less > $ZS_OUTDIR/styles.css 92 lessc < $ZS_OUTDIR/styles.less > $ZS_OUTDIR/styles.css
70 rm -f $ZS_OUTDIR/styles.css 93 rm -f $ZS_OUTDIR/styles.css
71 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
72 ## Command line usage 101 ## Command line usage
73 102
74 `zs build` re-builds your site. 103 `zs build` re-builds your site.
104
105 `zs build <file>` re-builds one file and prints resulting content to stdout.
75 106
76 `zs watch` rebuilds your site every time you modify any file. 107 `zs watch` rebuilds your site every time you modify any file.
77 108
78 `zs var <filename> [var1 var2...]` prints a list of variables defined in the 109 `zs var <filename> [var1 var2...]` prints a list of variables defined in the
79 header of a given markdown file, or the values of certain variables (even if 110 header of a given markdown file, or the values of certain variables (even if
80 it's an empty string). 111 it's an empty string).
81 112
82 ## License 113 ## License
83 114
84 The software is distributed under the MIT license. 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