yakumo_izuru/aya/README.md

# aya

aya is an extremely minimal static site generator written in Go.

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)

## Features

* Zero configuration (no configuration file needed)
* Cross-platform
* Highly extensible
* Works well for blogs and generic static websites (landing pages etc)
* Easy to learn (you literally don't need to)
* Fast (goes without saying)

## Installation

Build it manually provided you have Go (>=1.17) installed:

        $ svn co https://svn.chaotic.ninja/svn/aya-yakumo.izuru
        $ cd aya
        $ make
        # make install

(1) If you use this method, the `aya version` subcommand may print the wrong string,
but it should not be a problem unless you use it on a page.

You can also disable certain features at build time, with the `-tags` switch.
Currently, these tags are available: `noamber`, `nogcss`.
See `go help buildconstraint` for more details.

## Ideology

Keep your texts in markdown, [amber](https://github.com/eknkc/amber), or html format right in the main directory
of your blog/site.

Keep all service files (extensions, layout pages, deployment scripts etc)
in the `.aya` subdirectory.

Define variables in the header of the content files using [YAML](https://noyaml.com) :

```markdown
title: My web site
keywords: best website, hello, world
---

Markdown text goes after a header *separator*
```

Use placeholders for variables and plugins in your markdown or html
files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}.

Write extensions in any language you like and put them into the `.aya`
subdiretory.

Everything the extensions prints to [stdout](https://man.freebsd.org/cgi/man.cgi?fd) becomes the value of the
placeholder.

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:

* `$AYA` - a path to the `aya` executable
* `$AYA_OUTDIR` - a path to the directory with generated files
* `$AYA_FILE` - a path to the currently processed markdown file
* `$AYA_URL` - a URL for the currently generated page

## Example of RSS generation

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:

``` bash
#!/bin/sh
echo "Generating RSS feed"

echo '<?xml version="1.0" encoding="utf-8"?>' > $AYA_OUTDIR/blog/rss.xml
echo '<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">' >> $AYA_OUTDIR/blog/rss.xml
echo '<channel>' >> $AYA_OUTDIR/blog/rss.xml
for f in ./blog/*/*.md ; do
    d=$($AYA var $f date)
    if [ ! -z $d ] ; then
        timestamp=`gdate --date "$d" +%s`
        url=`$AYA var $f url`
        title=`$AYA var $f title | tr A-Z a-z`
        descr=`$AYA var $f description`
        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>"
    fi
done | sort -r -n | cut -d' ' -f2- >> $AYA_OUTDIR/blog/rss.xml
echo '</channel>' >> $AYA_OUTDIR/blog/rss.xml
echo '</rss>' >> $AYA_OUTDIR/blog/rss.xml
```

## Hooks
There are two special plugin names that are executed every time the build
happens - `prehook` and `posthook`. You can define some global actions here like
content generation, or additional commands, like LESS to CSS conversion

Note, you can also place `.gcss` files for [gcss](https://github.com/yosssi/gcss) to process instead

## Command line usage
Read `aya(1)`

## License
The software is distributed under the [MIT/X11](LICENSE) license.

---

Ayaya~
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 provided you have Go (>=1.17) installed:
19
20	$ svn co https://svn.chaotic.ninja/svn/aya-yakumo.izuru
21	$ cd aya
22	$ make
23	# make install
24
25	(1) If you use this method, the `aya version` subcommand may print the wrong string,
26	but it should not be a problem unless you use it on a page.
27
28	You can also disable certain features at build time, with the `-tags` switch.
29	Currently, these tags are available: `noamber`, `nogcss`.
30	See `go help buildconstraint` for more details.
31
32	## Ideology
33
34	Keep your texts in markdown, [amber](https://github.com/eknkc/amber), or html format right in the main directory
35	of your blog/site.
36
37	Keep all service files (extensions, layout pages, deployment scripts etc)
38	in the `.aya` subdirectory.
39
40	Define variables in the header of the content files using [YAML](https://noyaml.com) :
41
42	```markdown
43	title: My web site
44	keywords: best website, hello, world
45	---
46
47	Markdown text goes after a header separator
48	```
49
50	Use placeholders for variables and plugins in your markdown or html
51	files, e.g. `{{ title }}` or `{{ command arg1 arg2 }}.
52
53	Write extensions in any language you like and put them into the `.aya`
54	subdiretory.
55
56	Everything the extensions prints to [stdout](https://man.freebsd.org/cgi/man.cgi?fd) becomes the value of the
57	placeholder.
58
59	Every variable from the content header will be passed via environment variables like `title` becomes `$AYA_TITLE` and so on.
60	There are some special variables:
61
62	* `$AYA` - a path to the `aya` executable
63	* `$AYA_OUTDIR` - a path to the directory with generated files
64	* `$AYA_FILE` - a path to the currently processed markdown file
65	* `$AYA_URL` - a URL for the currently generated page
66
67	## Example of RSS generation
68
69	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:
70
71	``` bash
72	#!/bin/sh
73	echo "Generating RSS feed"
74
75	echo '<?xml version="1.0" encoding="utf-8"?>' > $AYA_OUTDIR/blog/rss.xml
76	echo '<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">' >> $AYA_OUTDIR/blog/rss.xml
77	echo '<channel>' >> $AYA_OUTDIR/blog/rss.xml
78	for f in ./blog//.md ; do
79	d=$($AYA var $f date)
80	if [ ! -z $d ] ; then
81	timestamp=`gdate --date "$d" +%s`
82	url=`$AYA var $f url`
83	title=`$AYA var $f title \| tr A-Z a-z`
84	descr=`$AYA var $f description`
85	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>"
86	fi
87	done \| sort -r -n \| cut -d' ' -f2- >> $AYA_OUTDIR/blog/rss.xml
88	echo '</channel>' >> $AYA_OUTDIR/blog/rss.xml
89	echo '</rss>' >> $AYA_OUTDIR/blog/rss.xml
90	```
91
92	## Hooks
93	There are two special plugin names that are executed every time the build
94	happens - `prehook` and `posthook`. You can define some global actions here like
95	content generation, or additional commands, like LESS to CSS conversion
96
97	Note, you can also place `.gcss` files for [gcss](https://github.com/yosssi/gcss) to process instead
98
99	## Command line usage
100	Read `aya(1)`
101
102	## License
103	The software is distributed under the [MIT/X11](LICENSE) license.
104
105	---
106
107	Ayaya~
nishi@chaotic.ninja	ViewVC Help
Powered by ViewVC 1.3.0-dev