From dba99be744a0dab7baf67ccae3b1c227c81b5eaa Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 12:59:46 +0000 Subject: [PATCH] Public-readiness: welcome-first README + reader guide + about doc Rewrite the root README for non-technical guests: a short welcome with Blima's biscotti, then clear paths to read the cookbook (download + install guide), browse recipes (by category or tag), the BlimaCake story, and plain-language rights. Move the technical/provenance/tooling detail into docs/about-this-archive.md so it stays available without crowding the front page. Add docs/read-the-cookbook.md, a step-by-step guide to opening BlimaCake.epub on Apple Books, Kindle, Kobo, Google Play Books, and other readers. Align the NOTICE contact to jeff@posluns.ca. Co-authored-by: Claude Claude-Session: https://claude.ai/code/session_01HpG2vky2XhDtfc6y16TRis --- CHANGELOG.md | 11 +++ NOTICE.md | 2 +- README.md | 158 ++++++++++++++----------------------- docs/about-this-archive.md | 88 +++++++++++++++++++++ docs/read-the-cookbook.md | 90 +++++++++++++++++++++ 5 files changed, 248 insertions(+), 101 deletions(-) create mode 100644 docs/about-this-archive.md create mode 100644 docs/read-the-cookbook.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e3d0c0..094479d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,17 @@ Recipe imports are logged both here (summary) and in ### Added +- **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 + (by category or tag), the "BlimaCake" story, and plain-language rights. Added + [`docs/read-the-cookbook.md`](docs/read-the-cookbook.md), a step-by-step guide to + opening `BlimaCake.epub` on Apple Books, Kindle, Kobo, Google Play Books, and other + readers, and [`docs/about-this-archive.md`](docs/about-this-archive.md), which now + holds the technical/provenance/tooling detail moved out of the README so it stays + available without crowding the front page. Aligned the `NOTICE.md` contact to + `jeff@posluns.ca`. + - **`tools/normalize_dashes.py` house-style guard.** Fails if any en dash (U+2013) or em dash (U+2014) appears in a `*.md` or `*.py` file, so the "no en/em dashes" convention cannot silently regress. (The guard stores the two characters via diff --git a/NOTICE.md b/NOTICE.md index ab868c4..eba42e4 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -30,7 +30,7 @@ good faith and promptly. **How to report:** - Open a GitHub issue using the **"Copyright / attribution concern"** template, or -- Email ****. +- Email ****. Please include, if you can: diff --git a/README.md b/README.md index 2c1eeb7..22d4459 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,59 @@ -# Blima Cake: Recipe Archive - -A durable, public-domain-bound document library of the recipes (and their -images) published on [blimacake.com](https://blimacake.com), my mother's -personal blog. - -This repository is the **canonical archive** of the recipes. It is designed to -outlive the WordPress site: every recipe is stored as portable Markdown with -machine-readable metadata, so the collection remains useful whether it is read -on GitHub, rendered as a static website, or migrated elsewhere. - -> **Status:** Private. This repository will be made public, and the chosen -> licence applied in full, once blimacake.com ceases operation. See -> [`GOVERNANCE.md`](GOVERNANCE.md) for the publication gate. - -## Scope - -| In scope | Out of scope | -| --- | --- | -| Recipes | The dogs' sections (Brie, Jackson, Chelsea) | -| Images used **within** recipes | Book / reading lists | -| | Any other non-recipe blog content | - -## What's here - -```text -recipes///index.md # one folder per recipe ("page bundle") - images/ # that recipe's images, co-located -_meta/ # taxonomy, provenance map, frontmatter schema -.working/ # AI hallucination tracking + import logs -.claude/ # Claude Code rules, skills config, hardening -.github/ # CI validation gates, CODEOWNERS, PR template -tools/ # deterministic WXR -> Markdown importer + validators -docs/adr/ # architecture decision records -``` - -A recipe is authored as Markdown with YAML frontmatter aligned to -[schema.org/Recipe](https://schema.org/Recipe). See -[`recipes/_TEMPLATE/index.md`](recipes/_TEMPLATE/index.md) and the schema at -[`_meta/recipe.schema.json`](_meta/recipe.schema.json). - -## Browse the recipes - -Start at the **[recipe index](recipes/README.md)** for a category-by-category -guide, or jump straight into a category; each has its own README listing every -recipe with a thumbnail. The index files are generated from recipe frontmatter by -[`tools/gen_readmes.py`](tools/gen_readmes.py); re-run it after adding recipes. - -## Read it as a book (EPUB) - -A ready-to-sideload e-book of the collection lives at the repo root: -**[`BlimaCake.epub`](BlimaCake.epub)**; load it onto a -Kindle, Kobo, or Apple Books. It gathers the recipes into numbered sections with -a navigable table of contents and photos, and it opens on Blima's signature -biscotti. Every entry has a three-level locator like `4.c.3` (section · letter · -item). Reusable components (frostings, glazes, fillings, streusels, sauces) are -printed **inline** in the recipes that use them and are **also** listed on their -own (savory ones under *Sauces & Rubs*, sweet ones in a *Frostings, Fillings & -Toppings* section), cross-referenced by locator both ways. - -The book is generated deterministically from the Markdown by -[`tools/build_epub.py`](tools/build_epub.py) (standard library + Pillow, no -pandoc); re-run it after content changes: - -```sh -python3 tools/build_epub.py # -> BlimaCake.epub -python3 tools/build_epub.py --no-images # tiny text-only build -``` - -## How recipes get here (provenance, not transcription) - -Recipes are **not** retyped by hand or by an AI. They are imported from a native -WordPress export (WXR XML) plus the media library by a deterministic converter -in [`tools/`](tools/). Every recipe records its `source_url` and `wp_guid` so it -can always be re-verified against the original. Ingredient quantities are the -highest-risk field; the import-fidelity discipline (see -[`.claude/rules/import-fidelity.md`](.claude/rules/import-fidelity.md)) requires -them to be quote-verified against source, with any discrepancy logged in -[`.working/hallucination-metrics.md`](.working/hallucination-metrics.md). - -## Licence & rights - -Blima Posluns' own original content here is licensed **CC BY 4.0** (attribution -to the author). The full, verbatim CC BY 4.0 legal code is in -[`LICENSE`](LICENSE). - -**Third-party content:** the blog spans many years and may include recipes, -text, or images taken or adapted from other sources that remain under someone -else's copyright. We make no claim over such material, and the CC BY 4.0 licence -applies only to Blima's own work. If you are a rights holder and recognise your -work, please see [`NOTICE.md`](NOTICE.md); we will correct attribution or -remove it on request. - -## Roadmap - -- **Phase 0: Scaffold** *(this commit)*: structure, governance, guard rails, tooling skeleton. -- **Phase 1: Importer**: WXR → Markdown converter, dry-run + human verification loop. -- **Phase 2: Full import**: all recipes + images, per-recipe verification. -- **Phase 3: Site** *(optional)*: static site + GitHub Pages, accessible and fast. -- **Phase 4: Publish**: flip public, apply licence in full, optionally redirect the domain. +# Blima Cake + +A platter of Blima's almond biscotti + +Welcome. This is the collection of recipes that **Blima Posluns** baked, cooked, and +shared for years on her blog, [blimacake.com](https://blimacake.com), gathered into +one place so they are easy to read, cook from, and keep. + +**487 recipes** in all: cakes, cookies and bars, main courses, salads, soups, breads, +Passover dishes, and much more. Every measurement is given in both cups and metric. + +## Read the cookbook + +The whole collection is also a free e-book you can read on your phone, tablet, Kindle, +Kobo, or Apple Books, with no internet needed once it is on your device. + +- **[Download the cookbook (BlimaCake.epub)](BlimaCake.epub)** (about 20 MB), or get + it from the **Releases** link on the right of this page. +- First time with an e-book? **[How to open it on your reader](docs/read-the-cookbook.md)** + has simple, step-by-step instructions for Apple Books, Kindle, Kobo, Google Play + Books, and more. + +## Browse the recipes here + +Prefer to read online without downloading anything? + +- **[All recipes, by category](recipes/README.md)**: a picture index of every category. +- **[Recipes by tag](recipes/tags.md)**: find things like chocolate, lemon, Passover, + or no-cook. + +Open any category, then any recipe, to see the ingredients and method with photos. + +## Why "BlimaCake"? + +When Jeff was in school, his friends would often come over and ask whether there was +any "Blima cake." Over time the two words ran together into one, and they would just +ask, "BlimaCake?" The name stuck, and it became the name of the blog and of this +collection. + +## Rights and reuse + +These recipes were gathered over many years. Many are Blima's own; others she tried, +adjusted, and made her own from cookbooks, magazines, friends, and family. Her own +work here is shared under a **Creative Commons Attribution 4.0 licence** +([CC BY 4.0](LICENSE)): you may copy, share, print, and adapt it, for any purpose +including commercially, as long as you credit Blima Posluns. + +Some items may still trace back to another author we could not identify. If something +here is yours and its copyright does not allow it to be included, please write to Jeff +at `jeff@posluns.ca` and it will be corrected or removed. Full statement: +[`NOTICE.md`](NOTICE.md). + +## About this collection + +Curious how it was put together, or want to help? See +**[How this archive was made](docs/about-this-archive.md)** for the story of the +import, how each recipe is checked for accuracy, the tools that build the e-book, and +how to contribute. diff --git a/docs/about-this-archive.md b/docs/about-this-archive.md new file mode 100644 index 0000000..dcc5009 --- /dev/null +++ b/docs/about-this-archive.md @@ -0,0 +1,88 @@ + +# How this archive was made + +This page is for the curious, and for anyone who would like to help. If you only want +to read the recipes or cook from them, the [front page](../README.md) and the +[cookbook](read-the-cookbook.md) are all you need. + +## What this is + +A durable, self-contained archive of the recipes from blimacake.com, the personal blog +of **Blima Posluns**. Each recipe is stored as a plain-text Markdown file with its +photos beside it, so the collection stays readable and portable long after the +original website is gone, whether it is read here on GitHub, opened as the e-book, +turned into a website, or moved somewhere else entirely. + +## Scope + +**In scope:** the recipes and the photos used within them. **Out of scope:** the +blog's non-recipe writing (the family dogs' pages, the book and reading lists, and +other posts). + +## What is in the repository + +```text +BlimaCake.epub # the whole collection as an e-book +README.md # the front page +recipes///index.md # one folder per recipe + images/ # that recipe's photos, kept beside it +recipes/README.md, tags.md # the browsing indexes (generated) +docs/ # this page, the reading guide, decision records +_meta/ # taxonomy, provenance map, recipe schema +tools/ # the deterministic import and build scripts +.working/ # process and accuracy logs +.claude/, .github/ # assistant rules and continuous-integration checks +``` + +Each recipe is Markdown with structured metadata aligned to +[schema.org/Recipe](https://schema.org/Recipe). The template is +[`recipes/_TEMPLATE/index.md`](../recipes/_TEMPLATE/index.md) and the schema is +[`_meta/recipe.schema.json`](../_meta/recipe.schema.json). + +## Provenance, not transcription + +The recipes were not retyped from memory or copied from the rendered web page. They +were imported from a native WordPress export of the blog, plus its photo library, by +deterministic scripts in [`tools/`](../tools/). Every recipe records where it came +from (`source_url` and `wp_guid`) so it can always be checked against the original. +Ingredient quantities are the highest-risk field, so they were quote-verified against +the source, and any catch or correction is logged in +[`.working/hallucination-metrics.md`](../.working/hallucination-metrics.md). + +## Curation + +Once the faithful import was complete, a defined set of tidy-ups was made, each by a +re-runnable script and each recorded in the [`CHANGELOG`](../CHANGELOG.md): + +- inline metric measurements alongside the original cups and ounces; +- a light, controlled set of tags for browsing; +- corrections of clear defects (missing units, garbled or truncated lines), with a + short "Source reference" note on the recipe whenever an outside recipe was consulted + to fill a gap; +- a readability pass over the cooking instructions for grammar and flow; +- consistent punctuation throughout. + +The rule that governs all of it: **never change a cook-from value.** The verbatim +baseline is preserved in the WordPress export and in the project's history. The +reasoning is written up in the decision records, +[ADR 0001](adr/0001-archive-architecture.md) and +[ADR 0002](adr/0002-curation-phase.md). + +## The e-book + +`BlimaCake.epub` is generated from the same Markdown by +[`tools/build_epub.py`](../tools/build_epub.py) (Python standard library plus Pillow, +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. + +## Rights + +Blima's own work is shared under [CC BY 4.0](../LICENSE). Some items may trace back to +other authors and remain under their copyright; the full statement, and how to ask for +a correction or removal, is in [`NOTICE.md`](../NOTICE.md). + +## Contributing and governance + +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. diff --git a/docs/read-the-cookbook.md b/docs/read-the-cookbook.md new file mode 100644 index 0000000..f371094 --- /dev/null +++ b/docs/read-the-cookbook.md @@ -0,0 +1,90 @@ + +# Read the cookbook on your phone, tablet, or e-reader + +The whole collection is also a free e-book, **`BlimaCake.epub`**, that you can read +in bed, in the kitchen, or on a plane, no internet needed once it is on your device. +It has a cover, a tap-to-jump table of contents, photos, and every recipe in both +cups and metric. + +An **EPUB** is just the standard e-book file, the same kind of file bookshops sell. +Almost every reading app can open it. Below is how to get it onto the app you use. + +## Step 1: download the file + +- **Easiest:** open the **Releases** page of this project and download `BlimaCake.epub` + from the latest release. (On the project's front page, click "Releases" in the + right-hand column.) +- **Or:** click **`BlimaCake.epub`** in the file list on the front page, then use the + **Download** button (the download icon near the top right of that file view). + +Save it somewhere you can find it, such as your Downloads folder or your phone's +Files app. Then follow the section below for your app. + +## Apple Books (iPhone, iPad, Mac) + +**iPhone or iPad:** + +1. Download `BlimaCake.epub` (Step 1). It usually lands in the **Files** app, in + Downloads. +2. Open **Files**, tap the `BlimaCake.epub` file, and it opens in **Books** + automatically. If it does not, tap and hold the file, choose **Share**, then + **Books**. + +**Mac:** + +1. Download the file. +2. Double-click it, or drag it onto the **Books** app icon. It appears in your + library under **Books**. + +Your library syncs across your Apple devices, so once it is on one, it shows up on +the others signed in to the same Apple account. + +## Amazon Kindle + +Kindle can read this book; Amazon converts it for you when you send it. The file has +no copy protection, so this works. + +Pick whichever is easiest: + +- **From a web browser:** go to `amazon.com/sendtokindle`, sign in, and drag + `BlimaCake.epub` onto the page. It appears on your Kindle and in the Kindle app + shortly after. +- **By email:** every Kindle account has a personal address ending in `@kindle.com` + (find yours under **Manage Your Content and Devices → Preferences → Personal + Document Settings** on Amazon). Email `BlimaCake.epub` to that address as an + attachment, from an email address you have approved there. +- **With the Send to Kindle app** on your computer or phone: install it, then + "add" or share `BlimaCake.epub` to it. + +It arrives under **Docs** (or your library) on the Kindle. + +## Kobo + +- **On your computer (most reliable):** connect the Kobo with its USB cable. It shows + up like a USB drive. Copy `BlimaCake.epub` into it, then safely eject. The book + appears in your library. +- **In the Kobo app on a phone or tablet:** use the app's import option to add the + `BlimaCake.epub` file from your device's storage. + +## Google Play Books + +1. On a computer, go to `play.google.com/books`. +2. Click **Upload files** and choose `BlimaCake.epub`. +3. It syncs to the Play Books app on your phone or tablet, signed in to the same + Google account. + +## Any other reader + +The file is a standard EPUB, so it also works in free apps such as **Calibre** or +**Thorium** (Windows, Mac, Linux), and **Librera** or **Moon+ Reader** (Android), +among many others. Open the app, choose "add to library" or "import", and pick +`BlimaCake.epub`. + +## Trouble? + +- **"I can't find the download."** On the project's front page, look for **Releases** + on the right, or click the `BlimaCake.epub` file name and use the Download button. +- **"The file won't open."** Make sure it finished downloading (it is about 20 MB), + and that you are opening it with a reading app, not a document editor. +- **Still stuck, or you would rather just read online?** You can also browse every + recipe on the project's front page without downloading anything.