--- a/README.md	Mon Dec 11 17:23:49 2023 +0000
+++ b/README.md	Tue Dec 12 14:09:17 2023 +0000
@@ -17,28 +17,33 @@
 
 Build it manually assuming you have Go (>=1.17) installed:
 
-	$ go install marisa.chaotic.ninja/aya/cmd/aya@latest
+	$ go install marisa.chaotic.ninja/aya/cmd/aya@latest (1)
 	--- or ---
 	$ git clone https://git.chaotic.ninja/yakumo.izuru/aya
 	$ 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.
+
 ## Ideology
 
-Keep your texts in markdown, or HTML format right in the main directory
+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]:
+Define variables in the header of the content files using [YAML](https://www.yaml.io) :
 
-	title: My web site
-	keywords: best website, hello, world
-	---
+```markdown
+title: My web site
+keywords: best website, hello, world
+---
 
-	Markdown text goes after a header *separator*
+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 }}.
@@ -46,10 +51,11 @@
 Write extensions in any language you like and put them into the `.aya`
 subdiretory.
 
-Everything the extensions prints to stdout becomes the value of the
+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:
+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
@@ -93,10 +99,7 @@
 	lessc < $AYA_OUTDIR/styles.less > $AYA_OUTDIR/styles.css
 	rm -f $AYA_OUTDIR/styles.css
 
-## Extras
-
-`aya` also supports generating `.html` and `.css` by means of using `.amber`
-and `.gcss` files. See more at [eknkc/amber](https://github.com/eknkc/amber) [yosssi/gcss](https://github.com/yosssi/gcss)
+Note, you can also place `.gcss` files for [gcss](https://github.com/yosssi/gcss) to process instead
 
 ## Command line usage