README.md

   1 # aya
   2
   3 aya is an extremely minimal static site generator written in Go.
   4
   5 Named after [Aya Shameimaru](https://en.touhouwiki.net/wiki/Aya_Shameimaru) from [Touhou 9.5: Shoot the Bullet](https://en.touhouwiki.net/wiki/Shoot_the_Bullet)
   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 (you literally don't need to)
  14 * Fast (goes without saying)
  15
  16 ## Installation
  17
  18 Build it manually assuming you have Go (>=1.17) installed:
  19
  20         $ go install marisa.chaotic.ninja/aya/cmd/aya@latest (1)
  21         --- or ---
  22         $ git clone https://git.chaotic.ninja/yakumo.izuru/aya
  23         $ cd aya
  24         $ make
  25         # make install
  26
  27 (1) If you use this method, the `aya version` subcommand may print the wrong string,
  28 but it should not be a problem unless you use it on a page.
  29
  30 ## Ideology
  31
  32 Keep your texts in markdown, [amber](https://github.com/eknkc/amber), or html format right in the main directory
  33 of your blog/site.
  34
  35 Keep all service files (extensions, layout pages, deployment scripts etc)
  36 in the `.aya` subdirectory.
  37
  38 Define variables in the header of the content files using [YAML](https://www.yaml.io) :
  39
  40 ```markdown
  41 title: My web site
  42 keywords: best website, hello, world
  43 ---
  44
  45 Markdown text goes after a header *separator*
  46 ```
  47
  48 Use placeholders for variables and plugins in your markdown or html
  49 files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}.
  50
  51 Write extensions in any language you like and put them into the `.aya`
  52 subdiretory.
  53
  54 Everything the extensions prints to [stdout](https://man.freebsd.org/cgi/man.cgi?fd) becomes the value of the
  55 placeholder.
  56
  57 Every variable from the content header will be passed via environment variables like `title` becomes `$AYA_TITLE` and so on.
  58 There are some special variables:
  59
  60 * `$AYA` - a path to the `aya` executable
  61 * `$AYA_OUTDIR` - a path to the directory with generated files
  62 * `$AYA_FILE` - a path to the currently processed markdown file
  63 * `$AYA_URL` - a URL for the currently generated page
  64
  65 ## Example of RSS generation
  66
  67 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:
  68
  69 ``` bash
  70 #!/bin/sh
  71 echo "Generating RSS feed"
  72
  73 echo '<?xml version="1.0" encoding="utf-8"?>' > $AYA_OUTDIR/blog/rss.xml
  74 echo '<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">' >> $AYA_OUTDIR/blog/rss.xml
  75 echo '<channel>' >> $AYA_OUTDIR/blog/rss.xml
  76 for f in ./blog/*/*.md ; do
  77     d=$($AYA var $f date)
  78     if [ ! -z $d ] ; then
  79         timestamp=`gdate --date "$d" +%s`
  80         url=`$AYA var $f url`
  81         title=`$AYA var $f title | tr A-Z a-z`
  82         descr=`$AYA var $f description`
  83         echo $timestamp "<item><title>$title</title><link>https://technicalmarisa.chaotic.ninja/blog/$url</link><description>$descr</description><pubDate>$(gdate --date @$timestamp -R)</pubDate><guid>http://technicalmarisa.chaotic.ninja/blog/$url</guid></item>"
  84     fi
  85 done | sort -r -n | cut -d' ' -f2- >> $AYA_OUTDIR/blog/rss.xml
  86 echo '</channel>' >> $AYA_OUTDIR/blog/rss.xml
  87 echo '</rss>' >> $AYA_OUTDIR/blog/rss.xml
  88 ```
  89
  90 ## Hooks
  91
  92 There are two special plugin names that are executed every time the build
  93 happens - `prehook` and `posthook`. You can define some global actions here like
  94 content generation, or additional commands, like LESS to CSS conversion:
  95
  96         # .aya/post
  97
  98         #!/bin/sh
  99         lessc < $AYA_OUTDIR/styles.less > $AYA_OUTDIR/styles.css
 100         rm -f $AYA_OUTDIR/styles.css
 101
 102 Note, you can also place `.gcss` files for [gcss](https://github.com/yosssi/gcss) to process instead
 103
 104 ## Command line usage
 105
 106 `aya build` re-builds your site.
 107
 108 `aya build <file>` re-builds one file and prints resulting content to stdout.
 109
 110 `aya serve` serves your site over HTTP.
 111
 112 `aya var <filename> [var1 var2...]` prints a list of variables defined in the
 113 header of a given markdown file, or the values of certain variables (even if
 114 it's an empty string).
 115
 116 `aya watch` rebuilds your site every time you modify any file.
 117
 118 ## License
 119
 120 The software is distributed under the MIT/X11 license.
 121
 122 ---
 123
 124 Ayaya~