From 45caf22a6c9fc70e0b76faa31a6c9e7d9382f487 Mon Sep 17 00:00:00 2001 From: Mirek Kratochvil Date: Fri, 21 Jul 2023 11:20:37 +0200 Subject: [PATCH] document more --- README.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ab2a0d0..8f09a6e 100644 --- a/README.md +++ b/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