Claude Opus 5andbdeshi
de1ce73430
The human asked for a demo extensive enough to review by hand, tracked as files, and kept current the way docs are. Generated filler cannot be reviewed — you cannot read a Go function and see what a reader sees — so the generator is deleted and `examples/demo-site/` is an ordinary site: 33 Markdown files, six pictures, site.yaml, a template override and static files. My reason for generating it was ADR-0011, and I had that rule wrong: it puts the *author's site root* outside this repository, not fixtures. conventions.md already keeps golden files in testdata/, and this is the same category one size up. Keeping both a generator and files would have been two sources of truth, so one had to go. Kept true by two gates rather than by good intentions. A table-driven test in internal/web serves the directory through the real handler with one case per feature — thirty-five of them, each naming what it proves — and verify.sh runs `khosra check` over it and fails on anything fatal. Adding a feature now means adding it to the demo and adding its case, and the build says so if you don't. Extensive on purpose: eleven dated posts so a section actually paginates, a four-chapter series so first/last are not the neighbours, a gallery with three JPEGs and an SVG so both the resampled and the untouched paths show, a Bengali-only bundle, a titleless status, a draft, a future date, an include, a nested extras tree, and a typography page that demonstrates what the engine will not do. Two expectations of mine were wrong and the demo corrected them: the site's own list template overrides *tag* listings too, so there are no group headings there — which turns out to be the better demonstration of ADR-0046, since the theme picking the flat shape is exactly the point. And template literal text is not escaped, so an apostrophe stays an apostrophe.
47 lines
2.7 KiB
Markdown
47 lines
2.7 KiB
Markdown
# 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).
|
|
|
|
```bash
|
|
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` (in `internal/web`) serves this directory through the real handler
|
|
and asserts one case per feature. A feature that changes shape breaks it.
|
|
- `khosra check` runs 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`.
|