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

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)

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