sebastianhaba / book-to-course

Book → interactive course

Turns a source book into a folder that works as a self-contained web course. The learner opens it in a browser, reads
explanations written for a complete beginner, plays with small animations, answers quizzes, writes code that is checked
by unit tests, and their progress is stored in a file next to the course.

The player (HTML/CSS/JS + a tiny Python helper) is fixed and already tested — your job is the content: read the
book carefully, then write lessons as JSON files. Scripts do everything mechanical.

<course>/
  index.html  assets/  serve.py  start.sh  start.bat  README.md     ← player (never hand-edit; refresh with init_course.py --update)
  content/course.json, content/<chapter-id>/chapter.json, 01-*.json … 99-test.json   ← YOU write these
  exercises/<dir>/  (starter files, tests, exercise.json, _solution/)               ← YOU write these for code exercises
  course/data.js                                                                    ← generated by build_course.py
  progress/progress.json                                                            ← learner progress (written by serve.py)
  .build/state.json, .build/plan.md, .build/source/                                 ← resume info + extracted book text

Scripts (all in scripts/, standard library only):

Workflow

Create a task list for the steps below. Use SendUserMessage for short progress notes — the learner-to-be may be away.

0. Resuming?

If the user mentions an existing course, attaches a course zip/folder, or says "next chapter": unzip/locate it and run
course_state.py DIR status. It prints the next chapter, the notes (terminology, running example, style decisions) and the
log. Continue at step 4 for that chapter. If player files look outdated, run init_course.py DIR --update.

1. Find the source and settle three things

Look for the book in the attachments (/mnt/user-data/uploads/), in the conversation, or on the linked computer. Ask only
what you cannot reasonably decide; otherwise state your assumption and go on:

• Course language — default: the language the user writes in (explanations, UI, quiz text). Code identifiers stay in English. The book may be in another language; translating while teaching is expected.
• Scope — default: the whole book (front/back matter such as covers, indexes, bibliographies is skipped automatically).
• Exercise toolchain (programming books) — default: the language the book teaches, if it is installed here (which go python3 node …). If not installed, still write exercises but say they could not be verified.

2. Extract and inspect

python3 scripts/extract_book.py /path/to/book.epub work/extract

Read work/extract/outline.md and the warnings. PDF exit code 2 means a scanned book — run ocrmypdf if available, or tell
the user an EPUB or text-based PDF is needed. PDF extraction is heuristic: when code, tables or math look garbled,
rasterize the page (pdftoppm -r 110 -f N -l N -png) and look at it, then fix the text from the picture. EPUB/HTML are
the cleanest sources.

Math-heavy PDFs are garbled more often than prose, because pdftotext maps the math font's glyphs to whatever
Unicode code point the PDF happens to embed — not necessarily the right one. Watch for: Greek letters (λ, θ, …)
silently vanishing from the extracted text; = turning into a lookalike character such as ⫽; ×/±/√ turning into
the wrong symbol or disappearing; matrices and multi-line equations collapsing onto one line with their layout lost. A
page that reads fine in prose but has a nonsensical equation ("fica Ax x com algum escalar") is this, not a typo in the
book — rasterize that page and transcribe the formula directly from the image into $...$/$$...$$ (references/math.md
has the supported LaTeX subset); don't try to guess the original from the garbled text.

3. Scaffold and plan

python3 scripts/init_course.py <course-dir> --extract work/extract [--ui-lang pl]

Write <course-dir>/.build/plan.md: the learning arc, one line per planned lesson with the source sections it covers
(this is the coverage map — every substantial section of every chapter must land in some lesson), the exercise idea for each
chapter, the running example if any, and the exercise toolchain. Then fill content/course.json (subtitle, description).
Sizing rule of thumb: one lesson per ~1,200–2,000 source words (at least 2 per chapter), plus one test lesson per chapter.
Record decisions that later batches must respect with course_state.py DIR note "…" (term translations, naming of the running example, tone).

4. Write the course chapter by chapter

For each chapter (course_state.py DIR next tells you which): set CH in_progress, then **read the whole chapter file in
.build/source/chapters/** (in slices if long) before writing — never write from memory of the topic; the course must reflect
this book's content and order. Then create content/<chapter-id>/chapter.json, lessons 01-….json …, a test lesson 99-test.json,
and exercises/<dir>/ for code exercises. Before writing the first lesson of a course, read:

• references/pedagogy.md — how to explain things to a beginner, theory/practice balance, quiz & test design
• references/lesson-schema.md — every block type and field (use only these)
• references/exercises.md — designing exercises whose unit tests check the learner's code (read when the book teaches programming)
• references/examples/ — a complete sample lesson (all block types), a chapter test, and a Go exercise folder with tests and _solution/ to copy the shape from

After finishing a chapter: build_course.py DIR (fix all errors; read warnings), verify_exercises.py DIR,
course_state.py DIR set CH done --note "…", add notes for continuity. Keep going to the next chapter.

5. Batching without losing your place

Long books don't fit in one go. Work chapter by chapter; state is saved after every chapter, so stopping anywhere is safe.
When context grows heavy, or after about 3 chapters in one sitting, run pack_course.py, deliver the zip, and tell the user
which chapter comes next and that they can say "continue the course" with the zip attached (or the folder linked). A partially
built course is fully usable: unfinished chapters simply don't appear yet.

6. Final checks and delivery

1. build_course.py DIR → no errors; practice share per chapter roughly 35–60%.
2. verify_exercises.py DIR → all OK. A SKIPPED exercise was not verified: say so plainly.
3. Optional but valuable: serve and look at it (python3 serve.py --no-browser &, then a headless browser or the built-in browser) — check one lesson renders and a quiz works.
4. pack_course.py DIR and send the zip with SendUserFile. If a folder on the user's computer is linked and they asked for it there, write the course into that folder instead.
5. Tell the user in 3–5 lines: unzip, run start.bat / ./start.sh (needs Python 3) or just open index.html; progress lives in progress/; what is covered and what is next (if partial). build_course.py --single-file preview.html yields one HTML file for a quick look without unzipping (progress then stays in the browser).

What makes a good result (and why)

• Whole book, in the book's order. The learner trusts the course to replace the book. Use the coverage map; mention in the final note anything deliberately left out.
• Beginner-first. Assume no prior knowledge of the subject: define each term before using it, one idea per block, concrete example before abstraction, analogies for hard ideas, code traced step by step with the stepper block.
• Own words, short quotes. Explain in your own words. from_book blocks are for short excerpts (≲100 words) or code listings from the book with a source reference; never paste long passages — the course is a learning aid, not a copy.
• Balanced. Each lesson alternates explanation and doing. build_course.py prints the theory/practice split — if a chapter is far outside 35–60% practice, rebalance.
• Exercises that can be trusted. For programming: describe what the program must do and which output it must produce, ship starter code that compiles, and unit tests that fail on the starter and pass on the reference solution — verify_exercises.py proves it. A broken test is far worse than a missing exercise.
• Quizzes teach. Every question has a hint and an explanation of why; wrong options come from real misconceptions, not trick wording.
• Stable ids. Give quizzes, exercises and flashcard sets explicit, descriptive ids (e.g. ch03-quiz-slices). Progress is stored by id; renaming or reordering blocks later would orphan it.
• No placeholders. Never ship "TODO", lorem ipsum, or lessons that only say "see the book".

Variants

• Non-programming books (history, language, theory): use quizzes, flashcards, reveal prompts, tables, SVG/flow diagrams, and selfcheck exercises (write-and-compare tasks with a checklist).
• Mathematics textbooks: write equations as $...$ (inline) or $$...$$ (display) in any md/text field — see references/math.md for the supported LaTeX subset. Use a derivation block for a worked example that proceeds line by line (one algebraic move per step, each with a why); use stepper for a numeric walkthrough instead when that reads more naturally. svg is still the right tool for geometry and freehand diagrams, not for equations. Practice means numeric questions (a typed answer checked within a tolerance — use it instead of fill whenever the answer is a number) and order of proof steps, not more reading.
• Language-learning books: heavy on flashcards, fill and order questions; keep example sentences from the book short.
• Figures in the book: don't copy images; re-draw the idea as an svg or flow block, or describe it in a table.
• Course language ≠ book language: translate explanations; keep code and official term names, adding the translation in terms.

Troubleshooting

• build_course.py refuses to write data.js while errors remain — fix them (messages name file, block and field). --force writes anyway (don't use for delivery).
• Page is blank → course/data.js missing or invalid; rerun build_course.py.
• "Run tests" button disabled → page was opened as a file; use start.sh/start.bat. The command to run by hand is shown on each exercise.
• Test toolchain missing on the learner's computer (e.g. no Go) → the exercise page says which program is needed; mention installation links in the course intro for the language taught.