README.md

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