From e9ee6d41e86aa429f9fb86d0e7777f237cff0719 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 13:18:28 +0000 Subject: [PATCH] Public-readiness (3/3): GitHub Pages static-site proposal (ADR 0003) Add ADR 0003 (Status: Proposed): a scoped, owner-facing proposal to present the archive as a recipe-blog website generated from the same Markdown and hosted on GitHub Pages. Covers goal, options with a recommendation (Eleventy), a PR breakdown, guardrails carried from ADR 0001/0002, a rough effort estimate, and open questions. Nothing is built. Also add a maintainer note in docs/about-this-archive.md on publishing BlimaCake.epub as a versioned GitHub Release, and link the proposal from that doc. Co-authored-by: Claude Claude-Session: https://claude.ai/code/session_01HpG2vky2XhDtfc6y16TRis --- CHANGELOG.md | 9 +++ docs/about-this-archive.md | 15 ++++ docs/adr/0003-static-site-phase.md | 124 +++++++++++++++++++++++++++++ 3 files changed, 148 insertions(+) create mode 100644 docs/adr/0003-static-site-phase.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 335e443..9327f64 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,15 @@ Recipe imports are logged both here (summary) and in ### Added +- **Static-site phase proposal ([ADR 0003](docs/adr/0003-static-site-phase.md)).** + A scoped, owner-facing proposal to present the archive as a friendly recipe-blog + website generated from the same Markdown and hosted on GitHub Pages: goal, options + (Jekyll / Eleventy / Hugo / Astro) with a recommendation, proposed PR breakdown, + guardrails carried from ADR 0001/0002, a rough effort estimate, and open questions + (domain, search, theme, analytics). Status is Proposed; nothing is built. Linked + from [`docs/about-this-archive.md`](docs/about-this-archive.md). Also added a + maintainer note there on publishing `BlimaCake.epub` as a versioned GitHub Release. + - **Guest-facing front door for going public.** Rewrote the root `README.md` to welcome non-technical readers first: a short welcome with Blima's biscotti, then clear paths to read the cookbook (download + install guide), browse the recipes diff --git a/docs/about-this-archive.md b/docs/about-this-archive.md index dcc5009..b465d8d 100644 --- a/docs/about-this-archive.md +++ b/docs/about-this-archive.md @@ -75,6 +75,13 @@ reasoning is written up in the decision records, no other tools required), so it can be rebuilt at any time and always matches the recipes here. See [Read the cookbook](read-the-cookbook.md) for how to open it. +The file is committed at the repository root, so the download link in the README +always points at the current build. For a tidy versioned copy, the owner can also +attach `BlimaCake.epub` to a **GitHub Release**: on GitHub, open **Releases** then +**Draft a new release**, choose a tag (for example `cookbook-2026-07`), give it a +title, drag `BlimaCake.epub` into the assets box, and publish. The release page then +carries a permanent, versioned download link that can be shared on its own. + ## Rights Blima's own work is shared under [CC BY 4.0](../LICENSE). Some items may trace back to @@ -86,3 +93,11 @@ a correction or removal, is in [`NOTICE.md`](../NOTICE.md). Corrections and additions are welcome. [`CONTRIBUTING.md`](../CONTRIBUTING.md) explains how to propose a change, and [`GOVERNANCE.md`](../GOVERNANCE.md) explains how changes are reviewed and how the collection is kept accurate. + +## Looking ahead + +A possible next phase would present the collection as a friendly website (the feel of +a recipe blog) generated from this same Markdown and hosted on GitHub Pages. It is +scoped, with options and a rough cost, in +[ADR 0003](adr/0003-static-site-phase.md); it is a proposal awaiting the owner's +decision, not built yet. diff --git a/docs/adr/0003-static-site-phase.md b/docs/adr/0003-static-site-phase.md new file mode 100644 index 0000000..b6789fc --- /dev/null +++ b/docs/adr/0003-static-site-phase.md @@ -0,0 +1,124 @@ + +# ADR 0003: Optional static-site phase (GitHub Pages) + +- **Status:** Proposed (awaiting owner decision) +- **Date:** 2026-07-07 +- **Deciders:** Jeff Posluns (owner) +- **Relates to:** ADR 0001 (architecture), ADR 0002 (curation phase) + +## Context + +The archive is complete and readable in three ways today: browsed on GitHub as +Markdown, opened as the `BlimaCake.epub` e-book, and cloned as portable files. The +owner has asked whether the collection can also be presented as a friendly website, +with the feel of "a WordPress blog with reference recipes like blimacake.com," once +the original site retires. + +This ADR proposes such a phase so the owner can decide with the scope and rough cost +in front of them. **Nothing here is built yet**; approving this ADR authorises the +work, it does not perform it. + +The important starting point is that the hard part is already done. The 487 recipes +are clean Markdown with structured frontmatter (title, category, tags, ingredients, +steps, yield, times, images, provenance), images are co-located, and the taxonomy and +tag vocabulary are governed. A website is a **new view over that same content**, not a +migration of it. The Markdown stays the single source of truth. + +## Goal + +A static, no-server website that: + +- looks and reads like a modern recipe blog (mobile-first, photo-forward, easy to + scan), rather than a code repository; +- has a home page, browsable category pages, a tag index, and a clean page per + recipe (photo, ingredients, method, yield/times, and a link back to the source); +- offers fast client-side search across all recipes; +- keeps each recipe's provenance visible and links out to `source_url`; +- offers the `BlimaCake.epub` download prominently; +- is generated deterministically from the existing Markdown and deployed to + **GitHub Pages**, so there is no server to run or pay for. + +## Options considered + +1. **Jekyll (GitHub Pages built-in).** Pages can build Jekyll with no separate + workflow. Lowest deploy friction, but the templating is dated, plugins are + restricted on Pages, and the content model would need reshaping to fit Jekyll's + conventions. +2. **Eleventy (11ty).** A JavaScript static-site generator that reads the existing + `recipes/**/index.md` and their frontmatter almost as-is. Flexible templating, + easy to emit schema.org Recipe JSON-LD from the frontmatter we already store, and + simple to theme. Deployed to Pages via a GitHub Actions build step. +3. **Hugo.** A very fast Go generator with mature blog and recipe themes. 487 pages + build in well under a second. Also deployed via Actions. Templating (Go templates) + is less approachable than Eleventy's for later hand-editing. +4. **Astro.** Modern and produces excellent output, but adds a component/build model + heavier than this content needs. + +## Recommendation + +**Eleventy (11ty), deployed to GitHub Pages via a GitHub Actions workflow.** It maps +most directly onto the frontmatter and folder layout already in the repo, keeps the +templating readable for future edits, and can emit Recipe JSON-LD (helpful for search +engines and rich results) straight from the fields we store. Hugo is a reasonable +alternative if raw build speed or an off-the-shelf theme is preferred; the decision is +not hard to reverse, since the input (the Markdown) is generator-independent. + +## Proposed scope + +Delivered as a small series of focused PRs, each with its own CHANGELOG entry, on the +same one-change-one-PR discipline as the rest of the archive: + +1. **Scaffold and data layer.** Add the generator config and collections that read + recipes by category and by tag from the existing frontmatter. Site output builds + into an ignored directory (for example `_site/`); it is **not** committed. +2. **Templates and theme.** Home, category index, tag index, and recipe page. A + mobile-first, photo-forward stylesheet with a print layout for cooking from a + printed page. Self-hosted assets and fonts only (no external hotlinking, matching + the archive's existing rule). +3. **Search and SEO.** Client-side search over a prebuilt index (for example Pagefind + or a small JSON index), plus Recipe JSON-LD and basic meta tags per page. +4. **Deploy.** A GitHub Actions workflow that builds the site and publishes to Pages + on merge to `main`. The existing CI gates (frontmatter/schema, images, + markdownlint, link check, secret scan) stay in force and are not weakened. + +## Guardrails (carried from ADR 0001 and 0002) + +- **The Markdown remains source of truth.** The site is a generated view. No + cook-from value (quantity, unit, temperature, time, yield, pan size, inline + conversion) is ever altered by the site build. +- **Deterministic and re-runnable.** The site is rebuilt from the Markdown; built + output and `node_modules/` stay out of the repo. +- **Provenance preserved.** Every recipe page keeps its `source_url`/`wp_guid` link + and any curation source-reference note. +- **Gates stay sacred.** The site workflow is additive; it does not relax any + existing check. +- **No secrets, no hotlinking.** Images and assets are served from the repo, as they + are today. + +## Rough effort + +Approximate, to be refined before any work starts: on the order of **three to four +focused PRs**, with the scaffold and a first themed page being the largest single +step and search/SEO/deploy being smaller increments. This is an estimate, not a +commitment; the exact shape depends on the theme chosen and on the search and domain +decisions below. + +## Open questions for the owner + +1. **Custom domain.** Once blimacake.com retires, should the DNS point at the Pages + site so the collection keeps its original address? (Pages supports a custom domain + with HTTPS.) +2. **Search approach.** Prebuilt static search (Pagefind) versus a small hand-rolled + JSON index. Recommendation: Pagefind, for zero-maintenance full-text search. +3. **Theme direction.** Start from a light custom theme, or adapt an existing + open-licensed recipe theme? A custom theme keeps the look closest to blimacake.com. +4. **Analytics and comments.** Recommendation: neither, to keep the site private-data + free and dependency-light, unless the owner wants a privacy-respecting counter. + +## Consequences + +- **If accepted:** the archive gains a public, browsable website that reads like a + recipe blog, with no server to maintain, generated from the same governed Markdown. + Work proceeds as scoped PRs; this ADR moves to **Accepted**. +- **If declined or deferred:** no change. The archive stays fully usable on GitHub, + as the e-book, and as portable files. This ADR can be revisited at any time.