add docs

README.md

@@ -61,14 +61,18 @@ markdown file produces one "main" resulting page at the "mount" location, and
 optionally several redirect pages and (additions to) category pages.
 
 All markdown files have to contain a YAML header that describes where the page
-should go and adds a few other formatting options. The whole content of the YAML header (together with some other data) is also made accessible to the Mustache templates -- that way you can smuggle custom contents to the HTML rendering machinery.
+should go and adds a few other formatting options. The whole content of the
+YAML header (together with some other data) is also made accessible to the
+Mustache templates -- that way you can smuggle custom contents to the HTML
+rendering machinery.
 
 #### YAML header format
 
 ##### Required options
 
 - `mount` (string): what should be the canonical URL of the page
-- `title` (string): the name of the page for display in templates and page links
+- `name` (string): the name of the page for display in templates and page links
+  (technically, the `name` is not required UNLESS you
 
 ##### Optional
 
@@ -78,12 +82,9 @@ should go and adds a few other formatting options. The whole content of the YAML
   search index.
 - `toc` (boolean or int, default `3`): if false, no ToC is generated for the
   page. Otherwise the integer sets the depth of the ToC.
-- `timestamp` (string): A description of the "timestamp" for the page,
-  typically the date of the last page modification. For any file, this value is
-  also defaulted from `<filename>.timestamp` (e.g., `mypage.md.timestamp`),
-  which simplifies generation of the timestamps by external software (see
-  `scripts/source-timestamps.sh` for an example of how to do that from `git`
-  history)
+- `order` (integer or string, defaults to `name` and then `mount`): order of
+  the page in page listings. Negative numbers and zero sort before strings,
+  positive numbers sort after strings.
 - `tags` (array of strings): list of `/`-separated hierarchical tags
   ("categories") that are assigned to the page. The page will be listed in the
   category listings accordingly.
@@ -95,9 +96,12 @@ should go and adds a few other formatting options. The whole content of the YAML
 ```md
 ---
 mount: /about-something
-title: About something
+name: About something
+order: -1
 toc: 2
 template: special.html
+tags:
+  - stuff/special
 ---
 
 # A page about something!
@@ -105,6 +109,19 @@ template: special.html
 Lorem ipsum etc., as usual.
 ```
 
+#### Example `tag-metadata.yml`
+
+```yaml
+"":
+  name: "Root tag"
+  extra_message_can_be_processed_by_template: "xxxx"
+test/attempts:
+  name: "Testing"
+  order: -1
+```
+
+`name` and `order` work just as with pages.
+
 ### Template syntax
 
 Reploy uses the "simple" vanilla