document more

README.md

@@ -47,7 +47,23 @@ documentation at the top of `scripts/make-search-index.js`. By default, this
 works with the minimal search implementation present in the default template
 (present in `assets/`, `templates/` and `pages/search.md`)
 
-### YAML options in page markdown
+### Markdown pages
+
+As the most important difference from many other site generators, there is
+**no** information implicitly leaking from the directory structure of the page
+sources into the structure of the site, and the minor cases where this happens
+are non-default or have to be explicitly defined.
+
+All pages should be stored in some of the (possibly multiple) source
+directories specified by the `-s` option. Directory layout does not matter, all
+markdown files are sourced (unless exempted by another options). Generally, one
+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.
+
+#### YAML header format
 
 ##### Required options
 
@@ -74,6 +90,21 @@ works with the minimal search implementation present in the default template
 - `redirect` (array of strings): list of mounts that should redirect to this
   page (useful e.g. for old URLs, etc).
 
+#### Example page
+
+```md
+---
+mount: /about-something
+title: About something
+toc: 2
+template: special.html
+---
+
+# A page about something!
+
+Lorem ipsum etc., as usual.
+```
+
 ### Template syntax
 
 Reploy uses the "simple" vanilla