Evaluate authoring framework: stay on Just the Docs vs. migrate (interactivity + p5.js a priority)

[jonfroehlich]

The question

Is Just the Docs (a documentation theme) still the right engine for what is really an interactive textbook? Several V2.0 pain points trace back to JtD/Jekyll being a docs tool rather than a textbook/interactive-content platform. This issue is to evaluate alternatives and decide before we invest heavily in JtD-specific implementations of #99/#100/#101.

Requirements (what the engine must serve)

• Maximum interactivity — now a first-class goal. Many newer lessons embed p5.js sketches; we want rich, ideally native/inline interactive content (live, possibly editable sketches), not just third-party iframes.
• Academic-textbook rigor: LaTeX-grade math, figure/equation/section cross-references (see Add LaTeX-style clickable, auto-numbered figure references #101), citations, multi-format output (HTML, maybe PDF/ePub).
• Executable code for the computational chapters (the signals/ module has Jupyter/Python content).
• Accessibility + SEO (active V2.0 workstreams).
• Longevity, open source, free hosting (GitHub Pages today), low ongoing maintenance.

Current state (what we'd migrate from / costs)

• Just the Docs v0.12.0 via remote_theme; ~100 Markdown lesson pages, heavy inline HTML, MathJax ($$...$$ only), custom CSS, callouts.
• Interactivity today is third-party runtime embeds, which is fragile:
  • p5.js: 22 files embed editor.p5js.org sketches (iframes) hosted in a personal p5 editor account.
  • Source code: emgithub.com embeds fetch .ino files live at view time (already migrated once when gist-it died — see Decide code-embedding strategy (single source of truth vs. alternatives) #100).
• These runtime embeds are invisible to screen readers/search and break if the external service goes down.

Candidate engines (with the interactivity lens)

Option	Interactivity / p5.js	Textbook strengths	Migration cost
Stay: Jekyll + JtD (+ #98)	Manual JS / iframes only	Familiar; content keeps moving	None
Astro + Starlight	Strong — island components can run p5 sketches inline/natively; great a11y/SEO/perf	Markdown/MDX, math via remark/KaTeX, cross-refs via plugins	Medium-high (MDX, strip Liquid)
Docusaurus (React/MDX)	Strong — React components for live sketches/simulators; versioning, Algolia search	Good, app-like	High (JS toolchain, MDX)
Quarto	Moderate — raw HTML/OJS/iframe; p5 not a first-class component	Best academic fit: native cross-refs (#101), executable Python for signals/, citations, PDF/ePub	Medium-high
Material for MkDocs	Weak-moderate — manual JS/iframes	Lowest-friction upgrade; great search/a11y/admonitions	Medium (convert Liquid + front matter)

The core tension

The "best interactive engine" (Astro/Starlight or Docusaurus — native p5/components) and the "best academic-textbook engine" (Quarto — math, cross-refs, executable code) pull in different directions. Given interactivity is now a stated priority, Astro + Starlight and Quarto are the two strongest candidates; the decision hinges on which axis dominates.

Relationship to other issues

This is upstream of:

• Add LaTeX-style clickable, auto-numbered figure references #101 (figure cross-refs) — Quarto provides this natively; Astro via plugin.
• Decide code-embedding strategy (single source of truth vs. alternatives) #100 (code embedding) — Quarto/Astro can include/execute source at build time.
• Standardize code-block formatting and enforce it in CI #99 (code-block standardization) — engine choice affects the convention.
• Evaluate moving to a GitHub Actions Jekyll deploy (enabler for V2.0) #98 (GitHub Actions deploy) — needed regardless if we stay on Jekyll; also the deploy target for any of these alternatives.

Decide this (or explicitly defer it) before sinking effort into JtD-specific versions of #99/#101.

Proposed next step

Low-risk proof-of-concept: port one module to the top candidate(s) and compare real rendered output + authoring feel + how cleanly p5 embeds become native. Suggested pilot module: signals/ (worst-maintained today and exercises math + executable Python), and/or a p5-heavy communication/ lesson to test interactivity.

Tasks

• Confirm hard requirements + rank them (interactivity vs. academic rigor vs. migration cost)
• Build a Quarto PoC of one module
• Build an Astro/Starlight PoC of one p5-heavy lesson
• Compare a11y/SEO output, build speed, authoring ergonomics, migration effort
• Decide: stay (+Evaluate moving to a GitHub Actions Jekyll deploy (enabler for V2.0) #98) vs. migrate, and to what

[jonfroehlich]

Related to #83 (preference for a ReadTheDocs-style UI: left chapter nav + right in-page TOC) — a relevant data point for the theme/framework decision.

[jonfroehlich]

Recalibration: Quarto deprioritized; lead candidate is Astro + Starlight

After discussion, refining the recommendation in the issue body.

Quarto deprioritized. Its headline strength is executable notebooks (Python/R/Julia) and scientific publishing — which is the axis we care least about:

• Our priority is web-native, JS interactivity (p5.js), and Quarto's interactivity story is OJS/Shiny/iframes, not native JS components — so p5 stays bolted-on rather than first-class.
• The Jupyter content that would justify Quarto is stale: signals/ already ships as static nbconvert HTML exports (pandemic-era), likely to be rewritten. Quarto's killer feature would be re-animating content we may retire. Low payoff.

Real decision axis = how natively the engine runs JS components. That points to:

• Astro + Starlight (lead). Islands architecture mounts a p5 sketch as an inline client component (client:visible) that we host — removing the fragile editor.p5js.org iframe dependency and even enabling an editable-sketch component. Content-first MD/MDX, strong a11y/SEO/perf, math via remark-math/KaTeX, and a built-in left-sidebar + right in-page-TOC layout that matches the ReadTheDocs feel from Read the docs UI #83.
• Material for MkDocs (fallback). Low-friction upgrade with great search/a11y/admonitions, but interactivity stays manual JS/iframes — weak on our top priority.
• Docusaurus. Capable (React/MDX) but heavier/app-like than a textbook needs.

Cost note: migrating off Jekyll means stripping Liquid + converting front matter regardless of target, so migration effort is ~equal across alternatives. Since cost is a wash, pick on capability → interactivity favors Astro/Starlight.

Sequencing unchanged: don't migrate mid-revision. Do #98 (GitHub Actions) now — it improves the current site and is the deploy target for any alternative. Then run a low-risk PoC: port a p5-heavy lesson (e.g., a communication/ p5.js lesson) into a native inline Starlight component to feel the difference.