{{ page.title }}

data/{subject}-curriculum.json → catalog + graph (status, curriculums, edges)
content/{subject}/{slug}/      → live page (one folder)
  _index.md, core.html, supplement.html, assets/, widgets/

• List — numbered cards; live chapters link from the whole card.
• Map (?view=tree) — Mermaid map with strand columns; live chapters link from the title only (→ + hover underline).
• Compare (?view=compare, Mathematics only) — curricula comparison doc (HTML partial, not JSON).
• Curriculum names (DSE, IB, …) appear only in the catalog, never inside lesson prose.
• Every chapter needs a description (1–2 sentences; map clamps to three lines).
• Adding a subject should only require updates in data/ and content/; templates stay unchanged.

Use this when the lesson is not written yet but should appear in the catalog roadmap.

1. Open data/{subject}-curriculum.json (e.g. data/math-curriculum.json).
2. Find the right strand and add a chapter object:

{
  "slug": "your-chapter-slug",
  "title": "Human-readable title",
  "description": "One or two sentences for list and map cards.",
  "status": "planned",
  "curriculums": ["DSE"],
  "tier": "non-foundation"
}

tier is optional — omit for foundation topics; non-foundation shows an Extension badge.

Use kebab-case slugs. No content/ files needed for planned chapters.

A live chapter needs a catalog JSON entry and a folder under content/{subject}/{slug}/.

1. Catalog entry

Set "status": "live" in data/{subject}-curriculum.json with description and curriculums.

2. Chapter folder

Add _index.md, core.html, optional supplement.html, assets/, widgets/*.tsx. Copy content/math/quadratic-equations/.

3. Build

bun run build:js syncs HTML and bundles widgets — no theme template or main.tsx edits.

Prerequisites are required edges in graph.edges. Strand chapters[] order is for the list only — it does not create arrows.

• from / to are chapter slugs (any strand).
• The graph must be acyclic (no cycles).
• Branch: one parent → many children. Merge: many parents → one child (multiple edges).
• Vertical position uses longest-path layering — a chapter sits below all ancestors.

"graph": {
  "edges": [
    { "from": "quadratic-equations", "to": "sequences-series" },
    { "from": "quadratic-equations", "to": "functions-graphs" },
    { "from": "functions-graphs", "to": "linear-programming" },
    { "from": "sequences-series", "to": "linear-programming" }
  ]
}

Verify at catalog map. Mermaid supports pan and zoom.

Prerequisites: Zola and Bun.

bun install
bun run build:js    # after frontend/ changes
zola serve          # http://127.0.0.1:1111
bun test            # layout tests for catalog map
bun run build       # production build

Commit themes/openfreebooks/static/js/ after build:js. Do not commit public/.

Optional image at the top of the catalog header for a subject (List and Map). Subjects without banner in data/catalog.json stay plain.

1. Prepare a 2:1 image (e.g. 2000×1000).
2. Optimize to WebP in static/catalog/banners/{subject-id}.webp — use ffmpeg with libwebp, or cwebp -resize 1400 0 -q 82 … if ffmpeg lacks WebP support.
3. Add "banner": "/catalog/banners/{subject-id}.webp" on the subject in data/catalog.json.
4. Verify at /catalog/?subject=… after bun run build:js && zola serve.