From 8040be1aee949f5f0e3db83880d3d3dd1a50f450 Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Wed, 10 Jun 2026 09:43:25 -0400 Subject: [PATCH] Docs: align WRITING.md and README with the implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - js: page-script paths are site-root-relative, not content-relative (AUDIT §7.1) - directory-form standalone pages need a dedicated Site.hs rule; flat content/.md is the generic form (§7.2) - portal table: add the missing Photography row (§7.3) - document the implemented-but-undocumented summary:, revised:, and keywords: fields, including a Revision dates section (§7.4) - default citation style is Chicago Notes Bibliography, not Author-Date; hover previews come from popups.js, not the deleted citations.js (§7.5) - history: entries may be authored in any order (sorted at build time); examples reordered newest-first (§3.5) - README: make watch runs Hakyll's live-reload preview server (§7.5) Co-Authored-By: Claude Fable 5 --- README.md | 5 ++- WRITING.md | 108 +++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 88 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 020b6f5..1b6affd 100644 --- a/README.md +++ b/README.md @@ -9,14 +9,15 @@ with a custom build system in `build/` and a Haskell + JS + Python toolchain. ```sh make build # one-shot production build into _site/ make dev # dev build (drafts visible) + local server on :8000 -make watch # cabal-watch rebuild (drafts visible) +make watch # Hakyll live-reload dev server (drafts visible) make clean # cabal run site -- clean make deploy # clean → build → sign → push → rsync to VPS ``` `make build` always runs `make clean` implicitly when invoked from `make deploy`. For day-to-day work, prefer `make dev` (which serves the site on -`http://localhost:8000`) or `make watch` (rebuilds on save without a server). +`http://localhost:8000`) or `make watch` (Hakyll's live-reload preview server, +which rebuilds on save and serves the site locally). **Run `make build` any time you add or replace binary assets** (JPEG/PNG figures, PDFs, music assets). `make dev` and `make watch` skip the diff --git a/WRITING.md b/WRITING.md index 4e8c37f..f375288 100644 --- a/WRITING.md +++ b/WRITING.md @@ -17,15 +17,22 @@ frontmatter fields, and every authoring feature available in the Markdown source | Fiction | `content/fiction/my-story.md` | `/fiction/my-story.html` | | Composition | `content/music/{slug}/index.md` | `/music/{slug}/` | | Standalone page | `content/my-page.md` | `/my-page.html` | -| Standalone page (with co-located assets) | `content/my-page/index.md` | `/my-page.html` | +| Standalone page (with co-located assets; needs a dedicated rule) | `content/me/index.md` | `/me.html` | | Draft essay | `content/drafts/essays/my-draft.md` | `/drafts/essays/my-draft.html` (dev only) | File names become URL slugs. Use lowercase, hyphen-separated words. -If a standalone page embeds co-located SVG score fragments or other relative assets, -place it in its own directory (`content/my-page/index.md`) rather than as a flat file. -Score fragment paths are resolved relative to the source file's directory; a flat -`content/my-page.md` would resolve them from `content/`, which is wrong. +Flat `content/.md` is the generic standalone form — any flat file dropped +into `content/` builds automatically. Directory-form standalone pages +(`content/my-page/index.md`) are **not** picked up by the generic rule; each one +requires its own dedicated `match` rule in `build/Site.hs`. The two existing +ones are `content/me/index.md` and `content/memento-mori/index.md` — follow +their pattern when adding another. + +The directory form exists for pages that embed co-located SVG score fragments +or other relative assets: score fragment paths are resolved relative to the +source file's directory, and a flat `content/my-page.md` would resolve them +from `content/`, which is wrong. --- @@ -65,9 +72,12 @@ subtitle: "An Optional Secondary Line" # optional; rendered below the title in date: 2026-03-15 # required; used for ordering, feed, and display abstract: > # optional; shown in the metadata block and link previews A one-paragraph description of the piece. +summary: | # optional; rendered in a "Summary" box near the abstract + A structured summary. **Markdown allowed** — bold, lists, multiple paragraphs. tags: # optional; see Tags section - nonfiction - nonfiction/philosophy +keywords: [lattices, simd] # optional; links to /bibliography// pages (list or comma-separated string) authors: # optional; overrides the default "Levi Neuwirth" link - "Levi Neuwirth | /me.html" - "Collaborator | https://their.site" @@ -79,7 +89,7 @@ further-reading: # optional; see Citations section - someKey - anotherKey bibliography: data/custom.bib # optional; overrides data/bibliography.bib -csl: data/custom.csl # optional; overrides Chicago Author-Date +csl: data/custom.csl # optional; overrides Chicago Notes Bibliography no-collapse: true # optional; disables collapsible h2/h3 sections repository: https://git.levineuwirth.org/levi/repo # optional; "Repository" link in metadata preprint: /papers/my-essay.pdf # optional; "Preprint" link in metadata (typeset PDF version) @@ -101,12 +111,20 @@ confidence-history: # list of integers; trend arrow derived from last two peer-status: under-review # optional; unreviewed (default) | under-review | peer-reviewed | published | retracted result-shape: mixed # optional; positive | negative | mixed | comparative | descriptive -# Version history — optional; falls back to git log, then to date frontmatter +# Version history — optional; falls back to git log, then to date frontmatter. +# Entries may be listed in any order — they are sorted by date at build time. history: - - date: 2026-03-01 # ISO date; unquoted is fine (the Haskell YAML parser keeps it as a string) - note: Initial draft - - date: 2026-03-14 + - date: 2026-03-14 # ISO date; unquoted is fine (the Haskell YAML parser keeps it as a string) note: Expanded typography section; added citations + - date: 2026-03-01 + note: Initial draft + +# Revision log — optional; drives the date shown on cards and list pages +# (see Revision dates section) +revised: + - date: "2026-04-10" + note: "expanded the section on typography" + - date: "2026-03-20" # note is optional per-entry --- ``` @@ -226,6 +244,7 @@ The top-level segment maps to a **portal** in the nav: | Miscellany | `/miscellany/` | | Music | `/music/` | | Nonfiction | `/nonfiction/` | +| Photography | `/photography/` | | Poetry | `/poetry/` | | Research | `/research/` | | Tech | `/tech/` | @@ -265,7 +284,8 @@ The URL part is optional. ## Citations -The citation pipeline uses Chicago Author-Date style. The bibliography lives at +The citation pipeline uses Chicago Notes Bibliography style +(`data/chicago-notes.csl`). The bibliography lives at `data/bibliography.bib` (BibLaTeX format) by default; override per-page with `bibliography` and `csl`. @@ -278,7 +298,7 @@ Multiple sources agree.[@jones2019; @brown2021] ``` Inline citations render as numbered superscripts `[1]`, `[2]`, etc. The -bibliography section appears automatically in the page footer. `citations.js` +bibliography section appears automatically in the page footer. `popups.js` adds hover previews showing the full reference. ### Further reading @@ -754,9 +774,8 @@ at the top of the catalog. ## Page scripts For pages that need custom JavaScript (interactive widgets, visualisations, etc.), -place the JS file alongside the content and reference it via the `js:` frontmatter -key. The file is copied to `_site/` and injected as a deferred `