Claude Opus 5andbdeshi
b5be77498e
`include: merge` in frontmatter splices a bundle's includes before the parse, so
a page assembled from several files is one document: one footnote list at its
end, numbered straight through, and an abbreviation defined anywhere reaching
every part. Moving the rendered block afterwards would have meant editing
goldmark's own markup; handing the parser one source gets the right answer from
it instead. Without the flag nothing changes — each fragment stays its own
document with namespaced ids, so no existing content re-renders.
Heading ids are unique under either model. Merging gets that free, because one
parse means one id set, but embedding did not: three `## Description`s across a
page and its fragments produced three identical anchors, and every link to them
landed on the first. A nested parse now shares the parent's id set, so the
second becomes #description-1 — goldmark's own suffixing, reaching across files
because they finally share the set it counts in.
Auditing for other policies the author could not reach found two more.
A heading may declare its anchor: `## Title {#stable-anchor}`. This is the one
that mattered most and nobody had asked for it — a derived id changes when the
text does, so rewording a heading silently broke every link to that anchor,
which is indefensible in an engine whose first value is that published addresses
are permanent.
`::toc{depth=2}` shortens a contents list, because a theme cannot know per page
how deep is useful and the author can.
Deliberately not added: a typographer toggle, a per-picture "do not resample",
icon overrides. No second user for any of them.
The hand-copied wiring in example_test.go drifted for the third time this
session — Compose this time, after the dialect and notation — each caught by a
demo case rather than by the copy. The latent row is now marked due, with what
moving the list would require.
examples/
demo-site/ is a complete khosra site, kept here to be read and served — the demonstration a person walks
through to see what the engine does, and the fixture the engine tests itself against (ADR-0051).
make demo # serves it at localhost:8080
khosra check -site examples/demo-site
It is content, not a fixture in disguise: every file is what an author would write. Two things keep it honest,
both in verify.sh:
TestTheExampleSiteExercisesEveryFeature(ininternal/web) serves this directory through the real handler and asserts one case per feature. A feature that changes shape breaks it.khosra checkruns over it and must report nothing fatal.
Adding a feature means adding it here, with a case in that test. A feature the example does not show is a feature nobody can see working, and the gates are what stop that from being optional.
What each part is for
| Path | Demonstrates |
|---|---|
site.yaml |
the two site-level settings: base and title |
content/posts/day-01…11 |
pagination — eleven dated posts against a page size of ten |
content/posts/first-light/ |
two languages, a directory bundle owning a picture, a figure with a caption |
content/posts/only-english |
the fallback chain, and a canonical link naming the variant actually served |
content/posts/renamed-thing/ |
slug moving an address, aliases keeping the old one working |
content/posts/unfinished |
a draft: invisible without -dev on |
content/posts/scheduled |
a future date: published by the clock, with nothing to run |
content/comics/the-long-monsoon/ |
a series — structural membership, sparse order, prev/next/first/last, an archive, and a landing page in two languages |
content/art/monsoon-studies/ |
a gallery: three JPEGs sized into a srcset, and an SVG left exactly as drawn |
content/writing/notes-on-water/ |
an include whose fragment has no URL, and an extras/ tree with a nested directory |
content/writing/typography |
what the engine does to prose, and what it deliberately does not |
content/pages/* |
undated bundles: reachable, and absent from every feed |
content/pages/bengali-only |
a bundle that exists in one non-default language only |
content/status/* |
a titleless bundle — legal, and the one check warning this site expects |
templates/list.html |
overriding a single named block and inheriting the document |
static/note.txt |
files served verbatim |
The one expected warning
khosra check reports the titleless status note. That is deliberate: titleless is legal, the theme falls back
to the bundle's key, and the warning exists so an author who did not mean it finds out. A fatal finding here
would fail verify.sh.