Decide code-embedding strategy (single source of truth vs. alternatives)

[jonfroehlich]

Background

Lessons currently embed code two ways:

1. Hand-pasted {% highlight %} snippets (the progressive teaching code) — manually maintained copies.
2. emgithub.com <script> embeds — the "single source of truth" idea: a client-side script fetches the full .ino live from github.com/makeabilitylab/arduino at page-load. (History note in website-dev.md: we already migrated once because gist-it.appspot.com went down.)

I previously favored the auto-pull approach for a single source of truth, but I'm no longer sure it's best.

Concerns with the current runtime auto-pull (emgithub)

• Third-party fragility — already bitten once. Every embed depends on emgithub being up at view time; if it dies (like gist-it did), all embeds break at once. We don't control it.
• Conflicts with our V2.0 accessibility & SEO goals. Code is injected at runtime, so it's not in the HTML at build time: screen readers don't see it, search engines don't index it, and a jekyll build of _site isn't self-contained (needs emgithub + GitHub reachable at view time).
• No version pinning — embeds track branch HEAD, so improving the repo can silently change an old lesson's "final program."
• Single-source benefit is partial — pedagogy needs curated fragments/progressive builds the whole-file embed can't provide, so snippets are hand-maintained anyway.

Options

• A. Keep hybrid as-is — simplest; keeps the runtime dependency + a11y/SEO blind spot.
• B. Build-time inlining via GitHub Actions (recommended) — fetch the arduino repo (submodule/checkout) during the build and inline the real file into static HTML, pinned to a tag/commit. Keeps single-source-of-truth AND makes code accessible/indexable/offline-safe. Depends on Evaluate moving to a GitHub Actions Jekyll deploy (enabler for V2.0) #98.
• C. CI sync script — a scripts/ tool copies canonical .ino files into the markdown/_includes on commit; stays on plain GitHub Pages; static output; mild tooling overhead.
• D. Drop auto-pull — treat the textbook as authoritative for shown code, link to the repo for the full file. Most robust/simplest; cost is manual sync discipline.

Decision needed

Pick a direction (leaning B, fallback D). If B, this depends on the GitHub Actions pipeline in #98.