Analytic Cravings

Source for https://vyaas.github.io.

Writing

One file per post, named for its date:

posts/20260725.md

Writing twice in a day? Add a slug. The date still comes from the leading eight digits; the whole stem becomes the URL:

posts/20260725-burial.md      ->  https://vyaas.github.io/20260725-burial

The slug is lowercase letters, digits and hyphens — anything else fails the build. It is only needed for the second post of a day: a bare 20260725.md alongside slugged files is fine, and existing posts keep their bare-date URLs.

---
title: "The Title"
---

First paragraph.

A stanza,
broken where you broke it.

Then:

make          # rebuild whatever changed
git commit -am "New post"
git push      # GitHub Pages serves the generated HTML directly

The date comes from the filename and the title from the front matter, so the index rebuilds itself. Nothing else needs editing.

The index runs newest day first and shows every post as a plain date, so a day with two entries shows that date twice — the slug lives in the link, not the label. Within a day, posts sort by slug in reverse, and a bare-dated file sorts last, reading as that day's first post:

20260725 - Continuity     ->  /20260725-continuity
20260725 - Burial         ->  /20260725-burial
20260725 - Good Morning   ->  /20260725

Choose slugs that fall in the order you want, or rename one to reorder them.

Front matter

Key	Effect
title:	Required. Shown as the heading on the page itself, and used for <title> and the index entry.
spacing: stanza	Put a blank line after every paragraph. Default is tight: paragraphs butt together, separated only by the 30pt first-line indent.
first: flush	Leave the opening paragraph unindented and unjustified.
lead: none	Start the text flush at the top, with no opening blank line.

Override the page's spacing for one paragraph by fencing it:

::: gap
This paragraph is followed by a blank line.
:::

::: tight
This one is not.
:::

What the markdown supports

Single newlines become line breaks, so poems are written as they read. smart typography is on: "quotes" become curly, ... becomes an ellipsis, --- becomes an em-dash. Escape any of them (\...) to keep it literal.

Math is written as $E = mc^2$ or $$...$$ and rendered by KaTeX at build time, so the published pages carry no JavaScript. Add --metadata math=1 handling in the Makefile only if a new post needs the KaTeX stylesheet; about/ already gets it.

Checking

make verify   # compares generated pages against the pre-migration originals
make serve    # preview at http://localhost:8000

make verify extracts the visible text from every page as it stands in git history and diffs it against the freshly generated page, character for character. It also checks that every line break lands where it used to, that no index link dangles, and that sources and published directories agree. It is the regression test for the build: if a template or filter change alters what a reader sees, it fails.

It accounts for the two intentional departures from the 2018 site: post pages now head with their title, and posts written since the reference are ignored when the old index is compared. Anything else that changes is a failure.

Other deliberate differences are declared in EXPECTED in tools/verify.py. There is currently one: the old hand-maintained index listed "Another point of view" for a page whose own title was "Another Point of View".

How it is built

posts/*.md ──┬─ pandoc ── build/template.html ──┬── YYYYMMDD[-slug]/index.html
             │            build/filter.lua      │
             │            build/katex.js        └── about/index.html
             └─ build/make_index.py ── pandoc ───── index.html

• build/filter.lua renders math through KaTeX, rewrites footnotes into the inline hover markup the about page uses, and tags paragraphs with the indented class.
• style.css is distilled from the eLyXer stylesheet the site used to ship (~1030 lines, of which ~120 were ever load-bearing). Values are carried over verbatim, including two quirks that are deliberate — see the comments there.
• vendor/katex/ holds katex.min.css and the woff2 faces, so nothing is fetched from a CDN and the pages work offline.

Requires pandoc, python3, and node with npm install run once.

History

Posts were written in LyX and exported to HTML by eLyXer 1.2.5 until 2018. tools/import_legacy.py converted those pages to the markdown in posts/, reading the originals from git rather than the working tree, so it can be re-run against any ref. The .tex and .lyx exports were removed once the port verified clean; they are still in git history, and were in any case the lossy copies — they had lost every curly quote the HTML had.