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