1 files changed, 29 insertions, 0 deletions
diff --git a/docs/typ/README b/docs/typ/README
new file mode 100644
index 00000000..175a7abb
--- /dev/null
+++ b/docs/typ/README
@@ -0,0 +1,29 @@
+docs/typ: the Typst documentation corpus
+
+  style.typ        the semantic elements (key btn chord word tag addr file
+                   cmd doc), the palette and the topic ids; the only place
+                   they are defined. Each element looks at target() and
+                   draws itself for paged output or emits HTML elements.
+  cheatsheet.typ   content: facts as markup and element calls, no layout.
+                   Later topics (tags, fs, config, ...) go beside it as
+                   their own content files, importing from style.typ.
+  cheatsheet-a4.typ
+                   an output wrapper: page, type, headings, then #include
+                   of the content. Future wrappers (book.typ, html.typ)
+                   sit beside it; wrappers hold no facts.
+
+Build (from the repo root):
+
+  typst compile --ignore-system-fonts docs/typ/cheatsheet-a4.typ
+  zig build cheatsheet -Dplatform=tty --prefix DIR   # DIR/share/doc/pardes/cheatsheet.pdf
+  typst compile --features html --format html docs/typ/cheatsheet.typ out.html
+
+Write #word("Name") for a builtin, #key("SPC f c") or #key("Ctrl-w") for
+keys, #tag("words", path: ...) for a default tagline, #doc("fs", section:
+"edit") to point at a topic. The unit test "docs/typ names only words,
+keys and default tags that exist" (src/config.zig) reads every .typ here
+and fails when one names a builtin, key binding or default tag that pardes
+no longer has. Only embedded fonts (Libertinus Serif, DejaVu Sans Mono),
+so output is the same on every machine. docs/typ/cheatsheet-a4.pdf is
+committed, as the other docs PDFs are; re-render it when the content
+changes.