1 files changed, 48 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..00f4df5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# Weft
+
+Weft is the small static-site generator used by `tjp.lol`. It recursively turns
+`page.md` into `page.html` and renders explicit `*.html.tmpl` and `*.xml.tmpl`
+outputs in place.
+
+```sh
+go build -o weft .
+./weft ../tjp.lol
+```
+
+Markdown uses CommonMark with GFM tables, strikethrough, task lists, and
+autolinks. Raw Markdown HTML is disabled. Optional YAML frontmatter is exposed
+as `.Meta`; the first H1 becomes `.Title` and is removed from `.Sections`.
+
+## Site templates
+
+All non-underscore `.tmpl` files are loaded into one named template set. Files
+ending in `.html.tmpl` or `.xml.tmpl` also render to the same path without the
+`.tmpl` suffix. Other `.tmpl` files only define reusable templates.
+
+Markdown pages execute one of these required definitions:
+
+- `page` for ordinary paths
+- `weblog` below `weblog/`
+- `note` below `notes/`
+
+Template data exposes the current page fields (`.Title`, `.Meta`, `.Sections`,
+`.OutputPath`, and so on) plus `.Pages`, a map containing each Markdown page at
+every ancestor directory. Helpers are `rel from target`, `sortPages pages key`,
+`filterPages pages key value`, `slicePages pages start end`, `joinSections`,
+`date value layout`, `rfc3339 value`, and `xml value`. Use `xml` around joined
+HTML when embedding it as escaped Atom `type="html"` content.
+
+Go templates' built-in `slice` can select rendered sections, for example
+`joinSections (slice .Sections 1)` after rendering a weblog lede separately.
+
+Weft validates generated internal links and XML before changing the site. It
+tracks ownership in `.weft-generated.json`, refuses to replace untracked files,
+removes only tracked stale outputs, and installs a completed build with rollback
+on write failure. Files and whole subtrees beginning with `_` are ignored.
+
+For cron, schedule the build after Syncthing's settling window and use the
+host's lock and logging tools, for example:
+
+```cron
+17 * * * * flock -n /tmp/weft.lock /usr/local/bin/weft /srv/tjp.lol >>/var/log/weft.log 2>&1
+```