Repository navigation
Decide code-embedding strategy (single source of truth vs. alternatives) #100
Copy link
Copy link
Open
Labels
code-examplesEmbedded source code, sketch/code links, .ino syncEmbedded source code, sketch/code links, .ino syncenhancementNew feature or requestNew feature or requestquestionFurther information is requestedFurther information is requestedv2.0Targeted for the Version 2.0 releaseTargeted for the Version 2.0 release
Description
Background
Lessons currently embed code two ways:
- Hand-pasted
{% highlight %}snippets (the progressive teaching code) — manually maintained copies. emgithub.com<script>embeds — the "single source of truth" idea: a client-side script fetches the full.inolive fromgithub.com/makeabilitylab/arduinoat page-load. (History note inwebsite-dev.md: we already migrated once becausegist-it.appspot.comwent 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 buildof_siteisn'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.inofiles into the markdown/_includeson 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.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
code-examplesEmbedded source code, sketch/code links, .ino syncEmbedded source code, sketch/code links, .ino syncenhancementNew feature or requestNew feature or requestquestionFurther information is requestedFurther information is requestedv2.0Targeted for the Version 2.0 releaseTargeted for the Version 2.0 release
Activity