Mercurial > yakumo_izuru > aya
annotate README.md @ 89:744541fee713 draft
Ayaya, why did I do that again?
| author | yakumo.izuru |
|---|---|
| date | Sun, 04 May 2025 02:19:10 +0000 |
| parents | 01ae2ad18ed1 |
| children | 82986500ae71 |
| rev | line source |
|---|---|
| 55 | 1 # aya |
| 8 | 2 |
| 55 | 3 aya is an extremely minimal static site generator written in Go. |
| 8 | 4 |
| 64 | 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) |
| 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) |
| 74 | 13 * Easy to learn (you literally don't need to) |
| 14 * Fast (goes without saying) | |
| 8 | 15 |
| 16 ## Installation | |
| 17 | |
|
86
897d57a7ec95
Add support for disabling features at build time
yakumo.izuru
parents:
83
diff
changeset
|
18 Build it manually provided you have Go (>=1.17) installed: |
| 8 | 19 |
| 88 | 20 $ go install mahou-no-mori.yakumo.dev/aya/cmd/aya@latest (1) |
| 64 | 21 --- or --- |
| 88 | 22 $ git clone https://git.yakumo.dev/yakumo.izuru/aya |
| 64 | 23 $ cd aya |
| 24 $ make | |
| 25 # make install | |
|
79
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
26 |
|
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
27 (1) If you use this method, the `aya version` subcommand may print the wrong string, |
|
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
28 but it should not be a problem unless you use it on a page. |
|
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
29 |
|
86
897d57a7ec95
Add support for disabling features at build time
yakumo.izuru
parents:
83
diff
changeset
|
30 You can also disable certain features at build time, with the `-tags` switch. |
|
897d57a7ec95
Add support for disabling features at build time
yakumo.izuru
parents:
83
diff
changeset
|
31 Currently, these tags are available: `noamber`, `nogcss`. |
|
897d57a7ec95
Add support for disabling features at build time
yakumo.izuru
parents:
83
diff
changeset
|
32 See `go help buildconstraint` for more details. |
|
897d57a7ec95
Add support for disabling features at build time
yakumo.izuru
parents:
83
diff
changeset
|
33 |
| 8 | 34 ## Ideology |
| 35 | |
|
79
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
36 Keep your texts in markdown, [amber](https://github.com/eknkc/amber), or html format right in the main directory |
| 38 | 37 of your blog/site. |
| 8 | 38 |
| 39 Keep all service files (extensions, layout pages, deployment scripts etc) | |
| 55 | 40 in the `.aya` subdirectory. |
| 8 | 41 |
|
86
897d57a7ec95
Add support for disabling features at build time
yakumo.izuru
parents:
83
diff
changeset
|
42 Define variables in the header of the content files using [YAML](https://noyaml.com) : |
| 8 | 43 |
|
79
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
44 ```markdown |
|
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
45 title: My web site |
|
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
46 keywords: best website, hello, world |
|
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
47 --- |
| 8 | 48 |
|
79
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
49 Markdown text goes after a header *separator* |
|
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
50 ``` |
| 8 | 51 |
| 52 Use placeholders for variables and plugins in your markdown or html | |
| 38 | 53 files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}. |
| 8 | 54 |
| 55 | 55 Write extensions in any language you like and put them into the `.aya` |
| 8 | 56 subdiretory. |
| 57 | |
|
79
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
58 Everything the extensions prints to [stdout](https://man.freebsd.org/cgi/man.cgi?fd) becomes the value of the |
| 8 | 59 placeholder. |
| 60 | |
| 80 | 61 Every variable from the content header will be passed via environment variables like `title` becomes `$AYA_TITLE` and so on. |
|
79
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
62 There are some special variables: |
| 8 | 63 |
| 55 | 64 * `$AYA` - a path to the `aya` executable |
| 80 | 65 * `$AYA_OUTDIR` - a path to the directory with generated files |
| 66 * `$AYA_FILE` - a path to the currently processed markdown file | |
| 67 * `$AYA_URL` - a URL for the currently generated page | |
| 8 | 68 |
| 38 | 69 ## Example of RSS generation |
| 70 | |
| 71 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 | 72 |
| 38 | 73 ``` bash |
| 64 | 74 #!/bin/sh |
| 75 echo "Generating RSS feed" | |
| 76 | |
| 77 echo '<?xml version="1.0" encoding="utf-8"?>' > $AYA_OUTDIR/blog/rss.xml | |
| 78 echo '<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">' >> $AYA_OUTDIR/blog/rss.xml | |
| 79 echo '<channel>' >> $AYA_OUTDIR/blog/rss.xml | |
| 80 for f in ./blog/*/*.md ; do | |
| 81 d=$($AYA var $f date) | |
| 82 if [ ! -z $d ] ; then | |
| 83 timestamp=`gdate --date "$d" +%s` | |
| 84 url=`$AYA var $f url` | |
| 85 title=`$AYA var $f title | tr A-Z a-z` | |
| 86 descr=`$AYA var $f description` | |
| 88 | 87 echo $timestamp "<item><title>$title</title><link>https://technicalmarisa.yakumo.dev/blog/$url</link><description>$descr</description><pubDate>$(gdate --date @$timestamp -R)</pubDate><guid>http://technicalmarisa.yakumo.dev/blog/$url</guid></item>" |
| 64 | 88 fi |
| 89 done | sort -r -n | cut -d' ' -f2- >> $AYA_OUTDIR/blog/rss.xml | |
| 90 echo '</channel>' >> $AYA_OUTDIR/blog/rss.xml | |
| 91 echo '</rss>' >> $AYA_OUTDIR/blog/rss.xml | |
| 38 | 92 ``` |
| 8 | 93 |
| 94 ## Hooks | |
| 95 There are two special plugin names that are executed every time the build | |
| 38 | 96 happens - `prehook` and `posthook`. You can define some global actions here like |
| 83 | 97 content generation, or additional commands, like LESS to CSS conversion |
| 8 | 98 |
|
79
7b122b71fcfa
A good time to finally release a stable version
yakumo.izuru
parents:
74
diff
changeset
|
99 Note, you can also place `.gcss` files for [gcss](https://github.com/yosssi/gcss) to process instead |
| 64 | 100 |
| 8 | 101 ## Command line usage |
| 83 | 102 Read `aya(1)` |
|
60
cf7277e42ece
Add serve function, update documentation accordingly
yakumo.izuru
parents:
55
diff
changeset
|
103 |
| 8 | 104 ## License |
| 83 | 105 The software is distributed under the [MIT/X11](LICENSE) license. |
| 8 | 106 |
| 67 | 107 --- |
| 108 | |
| 109 Ayaya~ |