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
  14 * Fast (duh!)
  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
  21         --- or ---
  22         $ git clone https://git.chaotic.ninja/yakumo.izuru/aya
  23         $ cd aya
  24         $ make
  25         # make install
  26
  27 ## Ideology
  28
  29 Keep your texts in markdown, 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 `.aya` 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 `.aya`
  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 `$AYA_TITLE` and so on. There are some special variables:
  53
  54 * `$AYA` - a path to the `aya` executable
  55 * `$AYA_OUTDIR` - a path to the directory with generated files
  56 * `$AYA_FILE` - a path to the currently processed markdown file
  57 * `$AYA_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 #!/bin/sh
  65 echo "Generating RSS feed"
  66
  67 echo '<?xml version="1.0" encoding="utf-8"?>' > $AYA_OUTDIR/blog/rss.xml
  68 echo '<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">' >> $AYA_OUTDIR/blog/rss.xml
  69 echo '<channel>' >> $AYA_OUTDIR/blog/rss.xml
  70 for f in ./blog/*/*.md ; do
  71     d=$($AYA var $f date)
  72     if [ ! -z $d ] ; then
  73         timestamp=`gdate --date "$d" +%s`
  74         url=`$AYA var $f url`
  75         title=`$AYA var $f title | tr A-Z a-z`
  76         descr=`$AYA var $f description`
  77         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>"
  78     fi
  79 done | sort -r -n | cut -d' ' -f2- >> $AYA_OUTDIR/blog/rss.xml
  80 echo '</channel>' >> $AYA_OUTDIR/blog/rss.xml
  81 echo '</rss>' >> $AYA_OUTDIR/blog/rss.xml
  82 ```
  83
  84 ## Hooks
  85
  86 There are two special plugin names that are executed every time the build
  87 happens - `prehook` and `posthook`. You can define some global actions here like
  88 content generation, or additional commands, like LESS to CSS conversion:
  89
  90         # .aya/post
  91
  92         #!/bin/sh
  93         lessc < $AYA_OUTDIR/styles.less > $AYA_OUTDIR/styles.css
  94         rm -f $AYA_OUTDIR/styles.css
  95
  96 ## Extras
  97
  98 `aya` also supports generating `.html` and `.css` by means of using `.amber`
  99 and `.gcss` files. See more at [eknkc/amber](https://github.com/eknkc/amber) [yosssi/gcss](https://github.com/yosssi/gcss)
 100
 101 ## Command line usage
 102
 103 `aya build` re-builds your site.
 104
 105 `aya build <file>` re-builds one file and prints resulting content to stdout.
 106
 107 `aya serve` serves your site over HTTP.
 108
 109 `aya 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 `aya watch` rebuilds your site every time you modify any file.
 114
 115 ## License
 116
 117 The software is distributed under the MIT license.
 118
 119 ---
 120
 121 Ayaya~