Recipe Library

A static recipe library hosted on GitHub Pages. Recipes are plain markdown files committed to the repo; a GitHub Action compiles them into index.json after every push; the site reads that file and does client-side search with no backend.

transcribe in Claude  →  ./add-recipe.sh  →  git push  →  Actions rebuild  →  site updates

---

Architecture

repo/
├── recipes/                        ← one .md file per recipe (source of truth)
│   └── chicken-mushroom-risotto.md
├── index.json                      ← auto-generated by CI, do not edit by hand
├── index.html                      ← the entire site: search, library, detail view
├── scripts/
│   ├── build-index.js              ← parses recipes/ → index.json (run by CI)
│   ├── validate.js                 ← previews and validates a single recipe file
│   └── test-grocery.js             ← regression tests for ingredient parsing/consolidation
├── .github/workflows/
│   └── build.yml                   ← triggers build-index.js on push to recipes/
└── add-recipe.sh                   ← CLI helper: validate → preview → commit → push

No build step. No npm. No dependencies. index.html is a single vanilla JS file. build-index.js uses only Node built-ins (fs, path). Node must be installed locally to run the helper scripts, but the live site needs nothing beyond a static file host.

---

One-time setup

1. Create the GitHub repo

git clone git@github.com:you/recipes.git
cd recipes
# copy all files from this package into the repo root
git add .
git commit -m "init recipe library"
git push

2. Enable GitHub Pages

In the repo on github.com:
Settings → Pages → Source → Deploy from branch → main / (root)

Your site will be live at https://you.github.io/recipes/ within a minute or two.

3. Make the script executable (first time only)

chmod +x add-recipe.sh

---

Day-to-day workflow

Step 1 — Transcribe in Claude

Open the Claude recipe library artifact. Use the Add Recipe tab:

1. Drop in 1–2 photos of a recipe card (HEIC or JPEG)
   • Image 1: front of card (ingredients)
   • Image 2: back of card (steps + photos)
2. Hit Transcribe Recipe — Claude reads both sides and produces markdown
3. Review in the editor, make any tweaks
4. Copy the markdown to a .md file on your computer

Alternatively, write or paste recipe markdown directly if you already have it.

Step 2 — Import with the helper script

./add-recipe.sh ~/Desktop/lemon-pasta.md

The script:

1. Copies the file into recipes/ if it isn't there already
2. Validates and previews — shows parsed title, tags, time, serves, step names, and any warnings or errors
3. Prompts before committing:
   • c — commit and push
   • e — open $EDITOR for fixes, then re-validate
   • a — abort (removes the copied file)
4. Pushes via SSH once you confirm

Step 3 — Wait ~30 seconds

GitHub Actions runs build-index.js, regenerates index.json, and commits it back. The site updates automatically. No manual deploy step.

---

Batch sync

If you've dropped several .md files into recipes/ manually and want to commit them all at once:

./add-recipe.sh

This validates every new or modified file in recipes/, shows the results, and commits + pushes only if all pass. Any file with errors blocks the whole batch.

---

Recipe format

# Recipe Title
tags: protein, vegetable, cuisine-style, cooking-method
time: 40min
serves: 2
source: HelloFresh

## Ingredients
- amount ingredient
- amount ingredient

## Steps

### 1. Step Name
- action detail
- action detail

### 2. Step Name
- action detail

Field reference:

Field	Required	Notes
# Title	✓	Synthesise from the dish if the card is cropped
tags:	✓	Main protein, key veg, cuisine, cooking method
time:	recommended	e.g. 40min
serves:	recommended	e.g. 2 or 2–4
source:	optional	Meal kit brand if known (HelloFresh, Blue Apron, etc.)

Filename: kebab-case-recipe-title.md
The validator will warn if the filename doesn't match the title slug.

Tags guidance: derive from main proteins, key vegetables, cuisine style, and cooking method. More is better for search — chicken, mushroom, arugula, risotto, arborio-rice, parmesan, italian is preferable to just chicken, italian. Tags are comma-separated and power the site's search ranking (tag matches outrank full-text matches).

---

Validation rules

validate.js (called automatically by add-recipe.sh) distinguishes:

Errors — must fix before import:

• No # Title heading
• No ## Ingredients section
• No ## Steps section
• Ingredients section is empty
• No ### N. Step Name headings in Steps

Warnings — review but can commit through:

• Missing or sparse tags:
• Missing time: or serves:
• Missing source: (this is often intentional)
• Filename doesn't match the title slug
• Very few ingredients (suggests incomplete transcription)

Run it standalone on any file:

node scripts/validate.js recipes/my-recipe.md

Exit code 0 = valid (possibly with warnings). Exit code 1 = errors to fix.

---

The site

Visit https://you.github.io/recipes/ from any browser, no login required.

• Library — all recipes as cards showing title, time, serves, source, and tags
• Search — filters by title, tags, and full text; tag matches rank higher
• Detail — full rendered recipe with ingredient list and steps
• Random — picks a recipe at random from the library
• Grocery list — select up to 5 recipes, click "Shopping List →" for a consolidated, printable checklist; duplicate ingredients are merged and quantities summed where possible

Keyboard shortcuts: / to focus the search box, Esc to return to the library.

---

Local preview

To browse the site locally before pushing:

# Any static file server works — Python is usually already installed:
python3 -m http.server

# Or with Node:
npx serve .

Then open http://localhost:8000.

To rebuild index.json locally after editing recipe files:

node scripts/build-index.js

---

Adding a recipe without the script

If you're on a machine without the repo checked out (e.g. your wife's computer), you can add a recipe entirely through the GitHub web UI:

1. Go to the repo on github.com
2. Navigate to recipes/
3. Click Add file → Create new file
4. Name it kebab-case-title.md, paste the markdown, commit
5. GitHub Actions rebuilds index.json automatically