docs/typ gets book and HTML wrappers over one chapter list

style.typ lists the chapters in reading order (guide, cheatsheet,
scripting, reference, building), each with its content file or none
while unwritten. book.typ sets them as an A4 book with a title page and
contents, the tutor read from src/tutor.txt last; html.typ sets them as
one HTML page with a nav of anchors. An unwritten chapter shows a
placeholder, so both compile before the topics exist.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

4 files changed, 100 insertions, 4 deletions

diff --git a/docs/typ/README b/docs/typ/README
index b86d7ef2..f1eff604 100644
--- a/docs/typ/README
+++ b/docs/typ/README
@@ -7,20 +7,33 @@ docs/typ: the Typst documentation corpus
   cheatsheet.typ     content: facts as markup and the calls below, no
                      layout. Later topics (guide, scripting, reference,
                      building) go beside it as their own content files.
-  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.
+  cheatsheet-a4.typ  output wrapper: the one-page A4 cheatsheet.
+  book.typ           output wrapper: an A4 book, title page, contents,
+                     every chapter, then the tutor (src/tutor.txt).
+  html.typ           output wrapper: one HTML page, every chapter under
+                     an anchor named by its id, then the tutor.
+                     Wrappers hold layout only, never facts.
+
+Chapters: `chapters` in style.typ lists them in reading order (guide,
+cheatsheet, scripting, reference, building), each with its content file,
+or none while it is not written (the outputs show a placeholder). To add
+a topic, write docs/typ/<id>.typ and set its `file`. Wrappers include it
+with heading offset 1, so its = headings sit under the chapter title.
 
 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
+  typst compile --root . --ignore-system-fonts docs/typ/book.typ
+  typst compile --root . --features html --format html docs/typ/html.typ pardes.html
+(--root . because book and HTML read the tutor from src/tutor.txt.)
 
 The contract for content files
 ------------------------------
 Start a content file with
   #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
+(a content file does not import page setup; the same file goes into the
+book, the HTML and, for the cheatsheet, the A4 page)
 and use plain markup (= headings, - lists, `raw`, *strong*) plus these.
 Never set page, fonts, colours or spacing in a content file; ask for a
 new function instead.
diff --git a/docs/typ/book.typ b/docs/typ/book.typ
new file mode 100644
index 00000000..26191fa7
--- /dev/null
+++ b/docs/typ/book.typ
@@ -0,0 +1,45 @@
+// The book: every topic in reading order, then the tutor. Facts live in the
+// content files named by `chapters` in style.typ; this is layout only.
+//   typst compile --root . --ignore-system-fonts docs/typ/book.typ
+// (--root . because the tutor is read from src/tutor.txt.)
+#import "style.typ": palette, mono, chapters, tutor-path
+
+#set document(title: "pardes")
+#set page(paper: "a4", fill: palette.paper, margin: (x: 22mm, y: 24mm))
+#set text(font: "Libertinus Serif", size: 10.5pt, fill: palette.ink, lang: "en")
+#set par(justify: true, leading: 0.6em)
+#show raw: set text(font: mono, size: 0.9em)
+#show heading: set text(fill: palette.tag-name)
+#show heading.where(level: 1): it => {
+  pagebreak(weak: true)
+  v(18mm)
+  text(size: 22pt, weight: "bold", it.body)
+  v(8mm)
+}
+
+// title page
+#page(numbering: none, {
+  v(1fr)
+  text(size: 34pt, weight: "bold", fill: palette.tag-name)[pardes]
+  v(4mm)
+  text(size: 13pt, style: "italic", fill: palette.tag-fg)[acme's tags and three buttons, helix's keys, terminals as panes, the editor as a 9P filesystem]
+  v(2fr)
+})
+
+#page(numbering: none, outline(depth: 2))
+
+#set page(numbering: "1")
+#counter(page).update(1)
+
+#for ch in chapters {
+  heading(level: 1, ch.title)
+  if ch.file == none {
+    text(style: "italic", fill: palette.tag-fg)[This chapter is not written yet.]
+  } else {
+    set heading(offset: 1)
+    include ch.file
+  }
+}
+
+= The tutor
+#text(size: 8pt, raw(read(tutor-path), block: true))
diff --git a/docs/typ/html.typ b/docs/typ/html.typ
new file mode 100644
index 00000000..2b7277e6
--- /dev/null
+++ b/docs/typ/html.typ
@@ -0,0 +1,23 @@
+// The HTML documentation: one page holding every topic in reading order,
+// each under an anchor named by its id, then the tutor.
+//   typst compile --root . --features html --format html docs/typ/html.typ pardes.html
+// One page because Typst 0.15's HTML export writes one document per run.
+#import "style.typ": chapters, tutor-path
+
+#set document(title: "pardes")
+
+#html.elem("nav", {
+  for ch in chapters [- #link(label(ch.id), ch.title)]
+  [- #link(<tutor>)[The tutor]]
+})
+
+#for ch in chapters [
+  #heading(level: 1, ch.title) #label(ch.id)
+  #if ch.file == none [_This chapter is not written yet._] else {
+    set heading(offset: 1)
+    include ch.file
+  }
+]
+
+= The tutor <tutor>
+#raw(read(tutor-path), block: true)
diff --git a/docs/typ/style.typ b/docs/typ/style.typ
index 64d96064..467577cc 100644
--- a/docs/typ/style.typ
+++ b/docs/typ/style.typ
@@ -33,6 +33,21 @@
   detached: "docs/detached.md",
 )
 
+/// The book's and the HTML's reading order. `file` is the content file
+/// in docs/typ, or none while the topic is not written yet (the outputs
+/// then show a placeholder). Wrappers include each with heading offset 1,
+/// so a file's `=` headings sit under its chapter title.
+#let chapters = (
+  (id: "guide", title: "Guide", file: none),
+  (id: "cheatsheet", title: "Cheatsheet", file: "cheatsheet.typ"),
+  (id: "scripting", title: "Scripting", file: none),
+  (id: "reference", title: "Reference", file: none),
+  (id: "building", title: "Building", file: none),
+)
+
+/// The tutor, shown as it is in the editor (`Tutor`), from the repo root.
+#let tutor-path = "/src/tutor.txt"
+
 #let html-out() = target() == "html"
 #let span(class, body) = html.elem("span", attrs: (class: class), body)
 #let m(s, fill: palette.ink) = text(font: mono, size: 0.92em, fill: fill, s)