Skip to content

Under the hood

explico does its work when the course is built, not when it is read. A course is a folder of plain files. One build turns it into a static site that any web host can serve, with no server code, no database, and no math rendering in the reader's browser.

From files to a site

  1. The content. Lessons are MDX files: Markdown with a few components for figures, tables, and collapsible notes. The rest is small JSON and YAML collections: the notation (every symbol and its meaning, units, and source), sources, competencies, knowledge-check questions, and abbreviations.
  2. One compile. A single pass reads the whole folder, validates every file against its schema, resolves every reference, and writes a manifest: lessons, notation, competencies, sources, cross-references, and diagnostics, with a hash of each file's content.
  3. The site. Astro and Starlight render the lessons. Math is rendered to HTML and MathML by KaTeX during the build, and every symbol in it is bound to its notation entry.
  4. The checks. The same build runs every enforced rule and fails with the file and line when something is wrong. See Authoring rules.

What a successful build guarantees

  • Every symbol is explained. A symbol in rendered math, in a lesson, a notation formula, a quiz question, or a figure, that has no notation entry fails the build. One symbol has one meaning per page, checked across the whole course.
  • Every reference resolves. Links to equations, tables, figures, notes, and sources point at something that exists, in this lesson or another.
  • The prerequisite graph holds. The author, or an assistant, states which lessons depend on which. The build checks that the graph has no cycles, that every lesson comes after what it depends on, and that nothing is orphaned. It validates the graph and never guesses it.
  • Every formula renders. A KaTeX error fails the build instead of showing up as red text on a reader's screen.
  • Two builds of the same content are identical. The manifest is byte-for-byte reproducible, so it can serve as a stable contract for a learning platform or an AI tool that reads the course.

Built for working with an AI assistant

  • A command line that reads the course. One command shows a lesson with exactly the notation, references, and assumptions it relies on, which is what an assistant needs to draft or revise it. Others list the rules in effect, report diagnostics by severity, check a single lesson quickly, and scaffold a new lesson or notation entry.
  • Located, repeatable diagnostics. Every finding names its rule, file, and line, and appears in VS Code's Problems panel. An assistant fixes it on the next pass, without a person relaying the error.
  • Guides shipped with the package. The authoring rules, a guide for agents working on a course, and a migration guide for every release are part of the npm package. An assistant upgrading a course follows the installed version's instructions instead of guessing from a changelog.

Reader features, without runtime cost

  • Interactive figures patch numbers, not math. A figure's formula is compiled against the page's real notation at build time. In the browser, the figure only replaces numbers inside the already-rendered equation.
  • Offline and print. Each lesson can be exported as one self-contained HTML file (styles, fonts, scripts, and figures included) that opens from disk without a network. A print layout keeps every section open or closed as the reader left it, and keeps links pointing at the published course.
  • Seams for a host. Progress tracking, analytics, and identity are small interfaces that ship as no-ops. A learning platform supplies real ones without changing a component.

Versions

The engine follows semantic versioning, and each course carries its own knowledge version over its content, with a changelog. Both appear to readers in the course's About panel, so a reader can tell which edition they are studying.

Setting up a course

explico is an npm package that a course adds as a development dependency, next to the Astro, Starlight, React, and KaTeX versions the course pins. The course provides its content folder and wires the engine into its Astro setup in three places. The playground is the reference setup, and credit-and-derivatives is the same setup at full scale.

pnpm add -D explico

In a lesson, the syntax an author (or assistant) writes looks like this:

[[velocity-vector]]             a symbol, linked to its notation entry
\label{eq:range}  [[eq-range]]  a numbered equation, and a reference to it
[@source-id; p. 42]             a citation with a page locator
{/* explico-allow N9: reason */}  an exception to rule N9, with its reason

Back to explico