course-studio
Turn source material (the user's documents, notes, papers or an outline plus sources) into a complete static, interactive lesson site, on this machine and for free. Plans lessons, writes each lesson as structured blocks with citations, records narration locally with site-narrator (Kokoro), adds diagrams, a quiz per lesson whose answers link to the proving sentence, a glossary with underlined terms and popovers, full-text search and saved reading progress, then builds a fast site that works on any static host with no server and no third-party requests. Optional short lesson videos with reel-studio. Use whenever the user wants a course, lessons, a tutorial series, a study guide, training material, an explainer site, "turn these documents into lessons", "make a course from my notes", "an e-learning site", a narrated or "read aloud" course, a quiz per chapter, or wants to update, re-narrate or check a course made this way.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/vinvirtual--course-studio)HTML
<a href="/listings/vinvirtual--course-studio"><img src="/api/listings/vinvirtual--course-studio/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# 1. course-studio (for Claude Code; any folder works if you only use the command line) git clone https://github.com/VinVirtual/course-studio ~/.claude/skills/course-studio # 2. site-narrator and its voice model (see its README for the full steps) git clone https://github.com/VinVirtual/site-narrator ~/.claude/skills/site-narrator python3 -m venv ~/kokoro/.venv ~/kokoro/.venv/bin/pip install kokoro-onnx lameenc curl -L -o ~/kokoro/kokoro-v1.0.onnx https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.onnx curl -L -o ~/kokoro/voices-v1.0.bin https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/voices-v1.0.bin # 3. optional: reel-studio, only for lesson videos (see its README) git clone https://github.com/VinVirtual/reel-studio ~/.claude/skills/reel-studio # 4. check ~/.claude/skills/course-studio/course check
The two other skills are found in their default places. To use them from somewhere else:
| Variable | Default | What | |---|---|---| | `COURSE_NARRATOR` | `~/.claude/skills/site-narrator` | site-narrator's folder (it must hold `narrate` and `player/player.js`) | | `COURSE_REEL` | `~/.claude/skills/reel-studio` | reel-studio's folder (it must hold `reel`) |
site-narrator's own variables (`KOKORO_HOME`, `NARRATE_PYTHON` and so on) apply as usual.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 97 lines
- ---
- name: course-studio
- description: Turn source material (the user's documents, notes, papers or an outline plus sources) into a complete static, interactive lesson site, on this machine and for free. Plans lessons, writes each lesson as structured blocks with citations, records narration locally with site-narrator (Kokoro), adds diagrams, a quiz per lesson whose answers link to the proving sentence, a glossary with underlined terms and popovers, full-text search and saved reading progress, then builds a fast site that works on any static host with no server and no third-party requests. Optional short lesson videos with reel-studio. Use whenever the user wants a course, lessons, a tutorial series, a study guide, training material, an explainer site, "turn these documents into lessons", "make a course from my notes", "an e-learning site", a narrated or "read aloud" course, a quiz per chapter, or wants to update, re-narrate or check a course made this way.
- ---
- # course-studio
- Local pipeline: **plan** the lessons from the sources → **write** each lesson as blocks with citations → **lint** → **narrate** with site-narrator → **build** a static site → **verify** → look at it in a browser. The site is plain HTML, CSS and a few small ES modules. It works on any static host (including a sub-folder), has no accounts and makes no requests to other servers.
- Skill folder: `~/.claude/skills/course-studio/` (written below as `$C`). Every command is `$C/course <command> [course-folder]`. `$C/course help` lists them.
- ```
- $C/course the command line (check, new, lint, narrate, video, build, serve, verify, test)
- $C/cli/lib/ loader, lint rules, glossary, quiz proofs, page rendering, build, verify
- $C/site/ the site's CSS, fonts and browser modules (copied into every build)
- $C/templates/ a one-lesson course that shows every block type
- $C/examples/how-rain-forms/ a finished 3-lesson course with recordings and its built site in dist/
- $C/README.md install, content format, licences, limits
- ```
- It builds on two other skills, called through their command lines:
- - **site-narrator** (required for narration): `~/.claude/skills/site-narrator`, or set `COURSE_NARRATOR`.
- - **reel-studio** (optional, only for `course video`): `~/.claude/skills/reel-studio`, or set `COURSE_REEL`.
- ## What it cannot do
- Say these to the user before starting if they matter:
- - **Static only.** No accounts, no server, no progress shared between devices. Progress lives in the reader's browser.
- - **Narration only for text known at build time.** Every text change needs `course narrate` again; until then that line is silent.
- - **Search, glossary and quiz are built from the lesson text.** There is no chatbot and no answer that is not in the lessons.
- - **Text you draft must be checked by a person.** You can only trace claims to the sources you were given; you cannot vouch for the sources.
- - **You cannot hear audio.** Verify recordings by numbers (count, seconds, size, not silent), never describe how they sound.
- ## Writing rules (the important part)
- The course is only as trustworthy as these rules. Follow all of them.
- 1. **Write from the user's sources only.** Read the sources first. Every fact in a lesson must come from one of them. Do not fill gaps from memory, even when you are sure.
- 2. **Cite.** Every lesson lists its `sources` (title, publisher, URL or a `citation` for print, `accessed` date). Every paragraph, list, callout, example, quote and figure has `"cite": ["source-id"]`. `course lint` makes it an error when a prose block with a digit, a percentage, a number word from ten upward, a fraction or multiple word (half, twice, double...) or research wording (study, research, survey, according to...) cites no source, and when a heading, summary, takeaway, recap line, quiz question or right answer, glossary definition or subtitle states such a number or word that no cited block states. It is a pattern check: it cannot tell whether the source really says it, so you still check that yourself.
- 3. **Never invent facts, figures, statistics, dates, names or quotations.** Quotes are copied exactly. Numbers are copied exactly, with their units.
- 4. **When you cannot trace a claim to a source**, either leave it out or keep it with `"confirm": "why it needs checking"` on the block (a non-empty reason). `course lint` prints every such block under "To confirm with the user". **Show that list to the user.** Once they answer, cite a source or remove the claim, then drop `confirm`. `course build --strict` refuses to build while any `confirm` remains: use it for the build that gets published.
- 5. **Plain language.** Short sentences (lint warns past 35 words), one idea per paragraph (past 120 words), a lesson a reader finishes in one sitting (past 1,400 words, split it). Explain a term the first time it is used and add it to the glossary.
- 6. **Quiz questions test the lesson, not trivia.** Each question has a `proof`: a sentence copied exactly from the lesson that shows the answer. Lint fails when the sentence is not in the lesson, and warns when the sentence does not say the answer. Wrong options must be clearly wrong from the lesson, not trick questions.
- 7. **Figures are explanations.** Draw original SVG diagrams (see "Figures") or use the user's images. Alt text says what the picture shows; the caption says what to notice. Never use an image the user has not supplied or that you cannot license.
- ## Workflow
- 1. **Check the machine**: `$C/course check`. It also runs `narrate check`.
- 2. **Agree the plan with the user**: audience, number of lessons (3 to 8 is typical), one sentence per lesson, which sources each one draws on. Read every source before writing.
- 3. **Scaffold**: `$C/course new <dir>`. Put the user's sources in `<dir>/sources/` (not published).
- 4. **Write** `course.json`, one `lessons/NN-name.json` per lesson, `glossary.json` and any `figures/`. Fields are in `README.md`; `templates/lessons/01-first-lesson.json` shows every block type.
- 5. **Lint**: `$C/course lint <dir>`. Fix every error. Read every warning. Show the user the "To confirm" list.
- 6. **Narrate**: `$C/course narrate <dir> --dry-run`, then without `--dry-run`. It writes `voice-lines.json` and `narrate.json`, records new and changed lines into `<dir>/voice/` with 2 workers, and runs `narrate verify`. Add pronunciations the voice will get wrong to `course.json` `voice.say` (`"NOAA": "Noah"`), then narrate again (only lines containing them are redone).
- 7. **Optional video**: `$C/course video <dir> [lesson-id ...]` makes a short landscape video per lesson with reel-studio (title, the lesson's section titles over the recap, a closing card). Only text already in the lesson is used. It takes minutes per lesson; ask first.
- 8. **Build**: `$C/course build <dir>` while drafting, `$C/course build <dir> --strict` for the version that gets published. It refuses when lint has errors (`--force` overrides; do not use it to hide problems). Keep the output in `<dir>/dist` or a new folder: it refuses the course folder, any folder containing it, and a non-empty folder it did not build.
- 9. **Verify**: `$C/course verify <dir>` must end in `ok`. It checks every link and anchor, that nothing loads from another server, page and asset sizes, that every narrated line on every page has a recording (by hashing the page text exactly as the player does), that recordings are not empty, short or silent, and accessibility basics (lang, one h1, heading order, alt text, labels, button and link names, duplicate ids).
- 10. **Look at it**: `$C/course serve <dir>` and open it in a headless browser (playwright-cli) at 1440, 768, 390 and 320 px, light and dark. Read the screenshots. Click a glossary term, answer a quiz question and follow its proof link, search with a typo, press Listen and confirm lines highlight in order with no `missing` warnings in the console. Fix what is wrong and build again.
- 11. **Deliver**: tell the user what was built (lessons, terms, questions, narration seconds and size), the "To confirm" list, the voice used and that they need to listen to it, and that `dist/` can be uploaded to any static host as is.
- After any text change: lint, narrate, build, verify again.
- ## Figures
- SVG files are inlined into the page so they follow the light and dark theme. Use these classes instead of fixed colours:
- | Fill | Stroke | Text |
- |---|---|---|
- | `c-ink`, `c-soft`, `c-faint`, `c-accent`, `c-paper`, `c-sunk`, `c-rule`, `c-tint`, `c-good` | `s-ink`, `s-soft`, `s-accent`, `s-rule` (with `stroke-width`) | default is ink in the sans face; `t-serif`, `t-soft`, `t-accent` |
- The build parses each SVG and keeps only plain shapes, text, groups, `defs`/`use`/`symbol`/`marker`, gradients, `clipPath`, `mask`, `pattern`, `title` and `desc`, with geometry and presentation attributes; links only as `#fragment` and `url()` only as `url(#id)`. It drops everything else (scripts, `style`, `foreignObject`, `image`, `a`, `animate`/`set`, every `on...` attribute), and lint reports anything it would drop as `unsafe-svg`: fix the file rather than relying on the strip. Leave out a background rectangle; the page draws the frame. Give each SVG a `viewBox` and no fixed `width`/`height`. PNG, JPEG, WebP and AVIF need `width` and `height` in the block.
- ## Inline markup
- Inside any text: `[[term]]` or `[[shown|term]]` marks a glossary term (lint fails if it is not in the glossary); `[label](https://...)`, `[label](lesson:id)`, `[label](lesson:id#section-id)`, `[label](glossary:term)`, `[label](#section-id)` or `[label](files/handout.pdf)` (a regular file inside the course folder; paths outside it, absolute or hidden are refused) make links. Glossary terms are also found and underlined automatically, once per lesson, except in headings and links. Section ids are the heading text in lower case with dashes.
- ## When something is wrong
- | Symptom | Cause and fix |
- |---|---|
- | `uncited-claim` | the block states a number or a research claim with no `cite`. Cite the source, or add `confirm` and ask the user |
- | `proof-not-found` | the quiz `proof` is not copied exactly from the lesson. Copy the sentence (inline markup is ignored, quote style is ignored) |
- | `answer-not-in-proof` | the proving sentence does not contain the answer's words. Pick the sentence that does |
- | `undefined-term` | a `[[term]]` is missing from `glossary.json`. Add it, or remove the brackets |
- | `missing-recording` in verify | the page's text changed since the last narration. Run `course narrate`, then `course build` |
- | `no-voice` in verify | no recordings at all: run `course narrate`; or `--no-voice` if the user does not want narration |
- | Listen buttons are missing | site-narrator was not found at build time, or the lesson has no recordings |
- | Nothing is interactive, or search says it could not load | the site was opened as a `file://` page, where browsers block ES modules. Serve it (`course serve`) or upload it |
- | `third-party` in verify | something loads from another server. Self-host it or remove it |
- | `unsafe-svg` | the SVG holds something the allowlist removes (the message lists it). Delete it from the file |
- | `uncited-claim` on a recap, takeaway, heading or quiz | it repeats a number or claim no cited block states. Say it in a cited block first, or drop the number |
- | build refuses the output folder | it is the course folder, contains it, or is a non-empty folder `course build` did not make. Use `dist/` or a new folder |
- ## Honesty
- Report only what you ran and looked at. List the claims the user must confirm. Say that the narration is a computer-generated voice that the user must listen to. Do not describe the audio.
README.md · README · 261 lines
- # course-studio
- [](https://github.com/VinVirtual/course-studio/actions/workflows/test.yml) [](LICENSE)
- Turn source material into a complete, narrated lesson site that works on any static host.
- 
- You give it the source material: your documents, notes or papers, or an outline plus the sources it should draw on. The lessons are written as small JSON files of blocks (headings, paragraphs, lists, callouts, worked examples, figures, code, quotes), each citing its sources. course-studio checks them, records every readable line with a local text-to-speech voice, and builds a static site: an index with reading progress, lesson pages with contents, read-aloud per section, a recap to play, a quiz whose answers link to the sentence that proves them, a glossary with underlined terms, full-text search and the next lesson. Nothing is uploaded and no paid service is used.
- It is packaged as a [Claude Code](https://claude.com/claude-code) skill (`SKILL.md` tells the assistant how to plan, write, cite and check a course), and it also works by hand from the command line.
- ## What you get
- - **`course`**, a command line: `check`, `new`, `lint`, `narrate`, `video`, `build`, `serve`, `verify`, `test`.
- - **A lint that guards the content**: blocks that state numbers or research claims without citing a source; recaps, takeaways, headings, summaries, quiz questions and answers, glossary definitions and the subtitle that state a number or claim no cited block states; sources that are cited but not listed; lessons, paragraphs and sentences that are too long; `[[terms]]` missing from the glossary; quiz answers whose "proof" sentence is not in the lesson or does not say the answer; broken lesson, section, glossary and file links; files outside the course folder; figures without useful alt text; SVG content the build would strip; an accent colour too pale to read. It prints every claim marked `confirm` (not traced to a source) for a person to check, and `course build --strict` refuses to build while any remain. "Claim" has an exact meaning here, listed under "Lint rules": it is a pattern match, not an understanding of the text.
- - **A built site** that is plain HTML, two small stylesheets (the layout and the generated theme colours), two self-hosted font families and a few small ES modules (17 KB of script gzipped, 9 KB of CSS gzipped for the example). Every page carries a Content Security Policy that only allows the site's own script files (no inline scripts or event handlers) and only loads styles, fonts, images, sound and video from the site itself:
- - index with lessons, minutes, progress, "continue" and a reset
- - lesson pages with a contents rail (it folds shut on phones and ticks off what you have read), "Listen" on every section, "Listen to the lesson" as a queue with skip and stop, the line being read highlighted, a voice on/off switch and a note that the voice is computer-generated
- - glossary terms underlined the first time they appear, with a popover (mouse, touch and keyboard; Escape closes it)
- - a quiz per lesson with feedback and a "See where the lesson says this" link that scrolls to the proving sentence and highlights it
- - search over every section and glossary term, with typo tolerance, opened with the Search button or `/`
- - numbered citations linking to each lesson's sources
- - light and dark themes (follows the system, with a switch), reduced motion respected, works from 320 px wide, keyboard accessible
- - reading progress and quiz scores kept in the browser's local storage, nothing sent anywhere
- - relative links only, so it works in a sub-folder (for example a GitHub Pages project site) as well as at a domain's root
- - **A verify step** for the built site: every link and anchor resolves (including each quiz question's link to its proving sentence), no `javascript:`, `data:` or `file:` address, nothing loads from another server, page and asset sizes, every narrated line on every page has its recording (found by hashing the page text exactly as the player does), no empty, short or silent recordings, and accessibility basics (lang, title, one h1, heading order, alt text, labels, button and link names, duplicate ids, captions on video).
- - **`examples/how-rain-forms/`**, a 3-lesson course written for this repository from public USGS and UCAR pages, with its narration (50 lines, 245 seconds, 956 KB) and its built site in `dist/`.
- ## Limits
- - **Static only.** There are no accounts, no server and no progress shared between devices or browsers. Clearing site data clears progress.
- - **Narration only for text known at build time.** Each line is a pre-recorded file named by a hash of its text. Edit a sentence and it has no recording until you run `course narrate` again (`course verify` reports it). Search results, quiz feedback and glossary popovers are not narrated.
- - **The voice is Kokoro's.** A fixed set of voices, no voice cloning, and pronunciations you may need to fix in `voice.say`. Someone has to listen to it: no tool here can judge how it sounds.
- - **Content drafted by an assistant must be checked by a person.** The lint catches uncited numbers and research claims, quiz answers the lesson does not support, and lists the claims marked for confirmation, but it cannot tell whether a cited source actually says what the sentence says, or whether the source is right.
- - **Search is word matching**, not a language model. It finds words (with small typos and the start of the last word), not meanings.
- - **It needs to be served over HTTP.** Opened from disk as `file://`, the pages and their text read fine, but browsers refuse to run the page's ES modules there, so read-aloud, the quiz, glossary popovers, search and progress do not work. Use `course serve` locally, or any static host.
- - **Lesson video is optional and simple**: a title card, the lesson's section titles over the recap, and a closing card, made by reel-studio. It is not a filmed or illustrated video.
- - **English first.** Sentence splitting (used for the sentence-length check) expects English punctuation and capitals, search trims English word endings only, and the claim check knows English number words only. Text in other scripts builds and is searchable as whole words: Cyrillic, Greek and other spaced scripts match whole words (no stemming; a different inflection does not match); Chinese, Japanese, Korean and Thai, which have no spaces, match any run of characters that contains the typed text. Lesson, section and glossary ids made from titles with no Latin letters are a short hash (`s-1a2b3c`), stable as long as the title does not change. Right-to-left layout is not handled.
- - Tested on Linux only (see "What was tested").
- ## Requirements
- | Needed | Why | Licence |
- |---|---|---|
- | Node.js 18.17 or newer | runs the command line, the build and the tests | MIT |
- | [site-narrator](https://github.com/VinVirtual/site-narrator) | records the narration (`course narrate`) and provides the browser player | MIT |
- | what site-narrator needs: Python 3.10+, kokoro-onnx, the Kokoro v1.0 model files, an MP3 encoder (lameenc or ffmpeg) | text to speech | see site-narrator's README: kokoro-onnx MIT, Kokoro-82M Apache-2.0, phonemizer and espeak-ng GPL-3.0-or-later, lameenc LGPL-3.0-or-later |
- | [reel-studio](https://github.com/VinVirtual/reel-studio) (optional) | short lesson videos (`course video`) | MIT; it needs Chrome or Chromium, playwright-core and ffmpeg, see its README |
- The site you build needs none of these: it is static files.
- Without site-narrator, `course build` still makes the site, with the Listen buttons left out, and `course verify --no-voice` checks it.
- ### Licence notes
- Checked on 21 November 2026. Check again before you rely on them. This is a summary, not legal advice.
- - **Bundled fonts** (`site/fonts/`): Instrument Serif (Copyright 2022 The Instrument Serif Project Authors) and Instrument Sans (Copyright 2022 The Instrument Sans Project Authors), both under the **SIL Open Font License 1.1**, as stated in the licence and copyright fields inside each font file. Neither declares a Reserved Font Name. The files here are subsets (Latin characters and common punctuation) converted to WOFF2 with fontTools. `site/fonts/OFL.txt` carries the notices and travels with the fonts into every built site.
- - **site-narrator and reel-studio** are separate projects under the MIT License, called through their command lines. Their own dependencies have their own licences, listed in their READMEs. Every built site includes a copy of site-narrator's `player/player.js` (MIT) as `assets/js/player.js`, with site-narrator's licence beside it as `assets/js/player.js.LICENSE.txt`; the example's `dist/` does too.
- - **The recordings in the example** were made with the Kokoro `af_heart` voice through site-narrator. Kokoro-82M is tagged Apache-2.0 on its model card; the voice files have no separate licence that could be checked.
- - **The example course text and figures** were written and drawn for this repository. Its facts come from the U.S. Geological Survey's Water Science School pages and the UCAR Center for Science Education page listed in each lesson; the text paraphrases them and does not copy them.
- - **Courses you make** are yours. Check the licences of the sources you quote and the images you add.
- course-studio's own code is under the **MIT License** (see `LICENSE`). The bundled fonts keep their own licence.
- ## Install
- ```bash
- # 1. course-studio (for Claude Code; any folder works if you only use the command line)
- git clone https://github.com/VinVirtual/course-studio ~/.claude/skills/course-studio
- # 2. site-narrator and its voice model (see its README for the full steps)
- git clone https://github.com/VinVirtual/site-narrator ~/.claude/skills/site-narrator
- python3 -m venv ~/kokoro/.venv
- ~/kokoro/.venv/bin/pip install kokoro-onnx lameenc
- curl -L -o ~/kokoro/kokoro-v1.0.onnx https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.onnx
- curl -L -o ~/kokoro/voices-v1.0.bin https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/voices-v1.0.bin
- # 3. optional: reel-studio, only for lesson videos (see its README)
- git clone https://github.com/VinVirtual/reel-studio ~/.claude/skills/reel-studio
- # 4. check
- ~/.claude/skills/course-studio/course check
- ```
- The two other skills are found in their default places. To use them from somewhere else:
- | Variable | Default | What |
- |---|---|---|
- | `COURSE_NARRATOR` | `~/.claude/skills/site-narrator` | site-narrator's folder (it must hold `narrate` and `player/player.js`) |
- | `COURSE_REEL` | `~/.claude/skills/reel-studio` | reel-studio's folder (it must hold `reel`) |
- site-narrator's own variables (`KOKORO_HOME`, `NARRATE_PYTHON` and so on) apply as usual.
- ## Quick start
- ```bash
- C=~/.claude/skills/course-studio/course
- $C new my-course # course.json, glossary.json, lessons/01-first-lesson.json, figures/, sources/
- # put the source material in my-course/sources/, then write the lessons (or ask Claude to)
- $C lint my-course # fix every error; confirm the listed claims
- $C narrate my-course # records my-course/voice/*.mp3 with site-narrator
- $C build my-course # writes my-course/dist/
- $C verify my-course # must end in "ok"
- $C serve my-course # http://127.0.0.1:4180/
- ```
- Upload `my-course/dist/` to any static host. Commit `voice/` with the course so recordings are not made again.
- ### The example
- ```bash
- $C serve ~/.claude/skills/course-studio/examples/how-rain-forms # then open http://127.0.0.1:4180/
- $C verify ~/.claude/skills/course-studio/examples/how-rain-forms
- ```
- ## Commands
- | Command | What it does |
- |---|---|
- | `course check` | checks Node, finds site-narrator (and runs `narrate check`) and reel-studio, and says how to fix what is missing |
- | `course new <dir>` | copies the template course into `<dir>`, which must be new or empty (it never overwrites files) |
- | `course lint [dir]` | checks the course (see "Lint rules"), prints the claims to confirm, exits non-zero on errors. `--strict` fails on warnings, `--json` prints JSON |
- | `course narrate [dir]` | runs lint, writes `voice-lines.json` and `narrate.json`, then `narrate record` (2 workers) and `narrate verify`. Only new and changed lines are recorded; recordings of removed lines are deleted. `--dry-run` shows the plan, `--force` records everything |
- | `course video [dir] [lesson ...]` | optional: writes a reel-studio project in `<dir>/video/` and renders a short landscape video per lesson (or the ones named) with its web copy, poster and captions. `course build` then adds them to the lesson pages |
- | `course build [dir]` | writes the site to `<dir>/dist` (`--out` elsewhere). Refuses when lint has errors (`--force` builds anyway). `--strict` refuses while any claim is still marked `confirm`: use it for the build you publish. The output folder may not be the course folder or a folder containing it, and a non-empty folder is only replaced when it holds a previous `course build` (its `build.json`). The site is built in a temporary folder next to it and swapped in only when the build succeeds |
- | `course serve [dir]` | serves the built site on `http://127.0.0.1:4180` (`--port N`, 0 to 65535). Local use only: it listens on this machine, answers only `localhost` requests and refuses dot-files. Supports single byte ranges (`bytes=a-b`, `bytes=a-`, `bytes=-n`), answers 416 for impossible ones |
- | `course verify [dir]` | checks the built site (see "What verify checks"), prints sizes and narration totals, exits non-zero on errors. `--no-voice` when the course has no narration, `--out` for another folder, `--json` |
- | `course test` | runs the unit tests (plain `node --test`, no extra packages) |
- `dir` is a folder holding `course.json` (default: the current folder). Unknown options are errors, so a typo stops the command instead of changing what it does.
- ## Content format
- ```
- my-course/
- course.json title, audience, lessons in order, theme, voice
- glossary.json [{ term, aliases?, definition, lesson? }]
- lessons/01-name.json one file per lesson
- figures/*.svg diagrams (inlined, they follow the theme)
- sources/ the source material (not published)
- voice/ recordings made by course narrate
- dist/ the built site
- ```
- ### course.json
- | Field | Meaning |
- |---|---|
- | `title`, `subtitle`, `audience`, `author`, `language` | shown on the index; `language` is the page's `lang` (default `en`) |
- | `lessons` | the lesson files, in reading order |
- | `glossary` | the glossary file (default `glossary.json` when it exists) |
- | `theme` | `{ "preset": "paper" | "ink" | "moss", "accent": "#175a72" }`: warm newsprint with clay red, cool blue-grey with cobalt, or lichen green; `accent` overrides the accent colour |
- | `voice` | `{ "voice": "af_heart", "speed": 0.96, "say": { "NOAA": "Noah" }, "lang": "en-us", "bitrate": 32 }`, passed to site-narrator |
- | `limits` | `{ "lessonWords": 1400, "paragraphWords": 120, "sentenceWords": 35, "recapLines": 6 }` for lint |
- | `video` | options for `course video`: `format` (`embed` by default, or `landscape`, `square`, `vertical`), `music` (false), `captions` (true), `speed`, `workers` (2) |
- | `footer` | the line at the bottom of each page |
- ### A lesson
- ```json
- {
- "id": "clouds",
- "title": "Clouds are made of droplets",
- "summary": "One or two sentences for the index and the lesson header.",
- "blocks": [
- { "type": "heading", "text": "Rising air cools" },
- { "type": "paragraph", "text": "Clouds form when the air cools below the [[dew point]].", "cite": ["ucar-clouds"] }
- ],
- "takeaways": ["Below the dew point, vapour condenses into liquid water."],
- "recap": ["Damp air rises, spreads out and cools."],
- "quiz": [
- { "question": "Why does rising air get cooler?", "options": ["...", "...", "..."], "answer": 1,
- "proof": "As the air rises it is under less pressure, so it spreads out and gets cooler." }
- ],
- "sources": [
- { "id": "ucar-clouds", "title": "Clouds and How They Form", "publisher": "UCAR Center for Science Education",
- "url": "https://scied.ucar.edu/learning-zone/clouds/how-clouds-form", "accessed": "2026-11-21" }
- ]
- }
- ```
- Block types and their fields (every block except `heading` and `code` takes `cite` and `confirm`):
- | Type | Fields | Read aloud |
- |---|---|---|
- | `heading` | `text` (starts a section) | yes |
- | `paragraph` | `text` | yes |
- | `list` | `items`, `ordered` | each item |
- | `callout` | `text`, `title`, `tone` (`note`, `tip`, `warning`) | title and text |
- | `example` | `title`, `steps`, `result` (a worked example) | title, each step, result |
- | `figure` | `src`, `alt`, `caption`, `width`, `height`, `credit` | the caption |
- | `code` | `text`, `lang`, `caption` | no |
- | `quote` | `text`, `by` | the text |
- `takeaways` are shown as a list. `recap` lines are read with "Play the recap". `quiz[].proof` is a sentence copied from the lesson. A source needs `id`, `title` and `url` (or `citation` for something with no address); `publisher` and `accessed` are shown when given. `"confirm": "why"` on a block marks a claim the writer could not trace to a source; the reason must be a non-empty text. Lint lists these for a person to check, and `build --strict` refuses while any remain.
- Inline markup in any text: `[[term]]`, `[[shown|term]]`, `[label](https://...)`, `[label](lesson:id)`, `[label](lesson:id#section-id)`, `[label](glossary:term)`, `[label](#section-id)`, `[label](files/handout.pdf)` (a regular file inside the course folder, copied into the site; absolute paths, `..` that leaves the folder, hidden files and folders are refused). Link targets may contain balanced parentheses, and `\[` `\]` for literal brackets. Glossary terms are also found and underlined automatically the first time they appear in a lesson.
- ### Figures
- SVG figures are inlined into the page and use classes instead of colours, so they follow the theme: fills `c-ink`, `c-soft`, `c-faint`, `c-accent`, `c-paper`, `c-sunk`, `c-rule`, `c-tint`, `c-good`; strokes `s-ink`, `s-soft`, `s-accent`, `s-rule`; text `t-serif`, `t-soft`, `t-accent`. The SVG is parsed and written back with an allowlist: shapes (`path`, `rect`, `circle`, `ellipse`, `line`, `polyline`, `polygon`), `text`, `tspan`, `g`, `defs`, `use`, `symbol`, `marker`, gradients, `clipPath`, `mask`, `pattern`, `title` and `desc`, with geometry and presentation attributes. Everything else is removed, including `script`, `style` elements and `style` attributes, `foreignObject`, `image`, `a`, `animate`, `set`, every attribute starting with `on`, any `href` that is not a `#fragment`, and any `url()` that is not `url(#id)`. Text is re-escaped, so markup cannot be reassembled from pieces. Lint lists what would be removed as an `unsafe-svg` error, so the file can be cleaned instead of silently changed. PNG, JPEG, WebP and AVIF are copied into the site and need `width` and `height`.
- ## Lint rules
- | Rule | Level | When |
- |---|---|---|
- | `shape` | error | a missing or unknown field, an unknown block type, a quiz `answer` out of range |
- | `no-sources`, `unknown-source`, `bad-source-url` | error | a lesson with no sources, a `cite` id not in the lesson's sources, a source URL that is not http(s) |
- | `uncited-claim` | error | a prose block with a claim and no `cite`; or a heading, lesson summary, takeaway, recap line, quiz question, right quiz answer, glossary definition, course title or subtitle with a claim that no cited block states (each number, number word and research word must appear in a cited block: of the same lesson, or of any lesson for the glossary and course). A claim is: a digit, `%`, the number words ten to nineteen and twenty to ninety, hundred, thousand, million, billion, trillion, dozen (and plurals), half, halves, twice, thrice, double, triple, quarter, percent or per cent, or the words study, studies, research, researchers, survey, according to, on average, estimate(d), "scientists found/say/estimate". "one" to "nine" are not counted. Wrong quiz options are not checked |
- | `unconfirmed-claim` | warning | a prose block with a claim and no `cite`, marked `confirm`: listed for the user, and `build --strict` fails |
- | `uncited`, `unused-source` | warning | prose with no citation, a source nobody cites |
- | `lesson-too-long`, `paragraph-too-long`, `sentence-too-long`, `recap-too-long` | warning | past the `limits` |
- | `no-recap`, `no-takeaways`, `no-quiz` | warning | a lesson without them |
- | `undefined-term`, `unknown-lesson` | error | a `[[term]]` not in the glossary, a glossary entry pointing at a lesson that does not exist |
- | `unused-term` | warning | a glossary entry that no lesson uses |
- | `proof-not-found` | error | a quiz `proof` that is not in the lesson text (quote style, dashes, `…` versus `...` and white space are ignored) |
- | `answer-not-in-proof` | warning | less than half of the right answer's words are in the proof or the question |
- | `duplicate-option` | error | two quiz options are the same |
- | `broken-link` | error | a lesson, section, glossary term or anchor that does not exist; a file that is missing, a folder, hidden, absolute or outside the course folder; or a scheme other than https, http, mailto, lesson, glossary |
- | `missing-image`, `remote-image`, `unsafe-svg`, `image-type` | error | a figure file that is missing or not a regular file inside the course folder, on another server, holds anything the SVG allowlist would remove (listed in the message), or is not SVG, PNG, JPEG, WebP, AVIF or GIF |
- | `accent-contrast` | warning | a `theme.accent` under 4.5:1 against the light backgrounds (the dark-theme accent is derived automatically to reach 4.5:1) |
- | `weak-alt`, `alt-is-caption`, `image-size` | warning | alt text that is short or generic or repeats the caption, a raster image without dimensions |
- ## What verify checks
- - every `href`, `src` and `poster` in the built pages resolves to a file inside the site, every `#anchor` to an element id, and every quiz question's proof link to a sentence on its page
- - no `href`, `src` or `poster` uses `javascript:`, `vbscript:`, `data:`, `blob:` or `file:` (white space and control characters inside the scheme are ignored, entities are decoded)
- - no script, stylesheet, image, video or font is loaded from another server (links to sources are fine), including `url()` and `@import` in CSS and `fetch()`/`import()` in scripts
- - one page over 200 KB, scripts over 80 KB gzipped, CSS over 30 KB gzipped (warnings)
- - every `[data-line]` element's text has `voice/<hash>.mp3`; recordings under 1.5 KB, shorter than 0.3 s or silent by the manifest's level are errors; recordings no page uses are warnings
- - `lang`, `<title>`, viewport, exactly one `<h1>`, no skipped heading level, `alt` on images, a name for `role="img"`, buttons, links and inputs, no duplicate ids, a captions track on video
- ## How it works
- 1. **Load and lint** (`cli/lib/load.mjs`, `lint.mjs`): the course is read into lessons of blocks. Inline markup is parsed into plain text plus marks (`text.mjs`), so the text a reader sees, the text that is recorded and the text the quiz proofs are matched against are the same string.
- 2. **Narrate** (`narrate.mjs`): the lines are collected in reading order (`blocks.mjs`: each section's heading and lines, then the recap) into `voice-lines.json`, and site-narrator records each into `voice/<key>.mp3`, where the key is 32-bit FNV-1a of the tidied text plus its length.
- 3. **Build** (`build.mjs`, `pages.mjs`, `blockhtml.mjs`, `inline.mjs`): each line is rendered inside its own `<span data-line>`, with glossary buttons, links and proof sentences nested inside it and citation numbers outside it, so the span's `textContent` is exactly the recorded line. The player (copied from site-narrator) hashes that text to find the file. The search index (`assets/search.json`) holds one entry per section, lesson and glossary term; `site/js/search-core.js` is shared by the build and the browser.
- 4. **Verify** (`verify.mjs`, `html.mjs`): the built HTML is scanned back, the `data-line` text is hashed the same way, and every link, asset and recording is checked on disk.
- ## What was tested
- On one Linux machine (Node 24, Google Chrome headless through Playwright, site-narrator with kokoro-onnx and the ffmpeg encoder):
- - `course test`: 97 unit tests for inline markup parsing (including decomposed Unicode and parentheses in links), SVG sanitising against known attacks, output-folder safety and staged builds, byte ranges in the local server, paths outside the course folder, claims outside blocks, theme contrast, progress keys, non-Latin slugs and search, the voice hash (also against the installed site-narrator player), loading and shape checks, sections and spoken lines, every lint rule, glossary marking, quiz proof matching, rendering and nesting of marks, link resolution, the HTML scanner, search (typos, prefixes, ranking, snippets), progress storage, link and anchor checking, third-party detection, accessibility checks, narration checks, the local server's path rules, and full builds of the example with and without site-narrator.
- - The example was linted (0 errors, 0 warnings, one claim listed to confirm), narrated (50 lines, 245 s, 956 KB; `narrate verify` ok), built and verified (`ok`).
- - The built example was opened in headless Chrome at 1440, 768, 390 and 320 px wide in light and dark: no horizontal overflow, no console errors (so no Content Security Policy violations), no request to any other origin. In the browser: a glossary popover opened by click and by keyboard (focus moved into it, Tab reached its link, Escape closed it and returned focus); a section's Listen read its heading and paragraph in order with the line highlighted; "Listen to the lesson" queued all sections, "Next section" skipped to the next one, the voice switch and Stop worked; the recap played its three lines; the quiz gave "right" and "not quite" feedback, the score was saved, and the proof link focused and highlighted the sentence; search found "Coalescence" from the typo "coalesense" and arrow keys moved through the results; reading to the end marked the lesson read, and the index showed it with the quiz score and pointed "Continue" at the first unread lesson; the theme choice survived a reload; reduced motion shortened transitions.
- - `course video` was run on one lesson of a copy of the example: reel-studio rendered a 25.6 s 1280×720 web copy with captions and a poster (563 KB, mean volume −23.1 dB), `course build` added it to the lesson page with a captions track, and it played in headless Chrome. It is not part of the committed example.
- Not tested: macOS and Windows; Firefox and Safari; real phones and screen readers; a real static host (only the local server); real courses in languages other than English (non-Latin slugs and search are covered by unit tests only). Nobody has listened to the recordings as part of these checks: listen to yours.
- ## Development
- ```bash
- ./course test # unit tests
- ./course lint examples/how-rain-forms
- ./course build examples/how-rain-forms && ./course verify examples/how-rain-forms
- ```
- The browser code is in `site/js/` (no build step, no dependencies). The command line is in `cli/`. Text handling that can be tested without a browser or a voice model lives in `cli/lib/` and `site/js/search-core.js`, `site/js/progress-core.js`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.