InteractiveCodeScroll
Scroll-driven code tutorials that work on stage and at home.
Write the story in MDX, keep your code runnable, and get a static site where explanations, highlighted code, live Preview and request results move together as readers scroll — or as you click through on stage.
Live demo · Features · Docs · Examples · Report a bug / request a feature
Start in 30 seconds
https://github.com/user-attachments/assets/ca9f9dc5-aad5-4f57-bc1f-159b278f2dec
npm create interactive-code-scroll@latest my-tutorial
cd my-tutorial
npm run dev
The wizard asks for one tutorial or a series, what each tutorial uses (web app, REST API, script, native app and their languages), your package manager, whether to add a GitHub Pages workflow and which coding agents to set up with the bundled agent skills. It writes a working example you can edit right away.
Why
Tutorials split into dozens of code blocks are hard to follow. At conferences, speakers jump between slides and an IDE, and attendees go home without a way to replay the session. InteractiveCodeScroll gives you one artifact for both: projected in the talk, read at home, downloaded as a runnable project.
Built for people who teach developer technologies: developer advocates, trainers, technical writers and conference speakers.
Features
| |
|---|
| 🧭 Scroll-synced steps | Each step focuses a file, a code region or an image carousel. Deep links to any step. |
| 📱 Desktop and mobile | Side by side on a laptop or projector; on phones the code sits on top and the explanation scrolls below. |
| 🎤 Presentation mode | Clean, projector-friendly layout. Keyboard and clicker (PageUp/PageDown) navigation, a large step index, and Alt+P, O and E shortcuts. |
| 🌐 Multi-language variants | One tutorial, several languages (e.g. cURL / Python / JavaScript). Readers switch in place. |
| ▶️ Live Preview | Web code runs in an embedded Preview, with an "open in new tab" fallback. |
| 📡 Request runner | Readers run .http requests from the page; captured output shows before Run and on network failures. JSON viewer included. |
| ✏️ Fields → code variables | Readers type their own API key or title; code, Preview and downloads update. |
| 📦 Copy & ZIP downloads | Readers leave with a runnable project, markers stripped. |
| 💬 Ask about a selection | Readers select a sentence or a line of code and ask the author (a prefilled issue) or an AI assistant, with a link back to that spot. |
| 📚 Series sites | Many tutorials in one site, with a searchable index, favorites and sibling tutorials across SDKs. |
| 🚀 Static output | Deploy anywhere. A GitHub Pages workflow is one wizard answer away. |
| 🌗 Light and dark | Follows the reader's system preference, with a toggle. |
See every capability in Features.
How it works
Your code stays plain and runnable. Comments mark the regions a step focuses on and the values readers can edit:
// #region config
const title = "My tutorial"; // @var title
// #endregion config
MDX steps point at files and regions:
<Step id="configure" file="main.js" region="config">
## Configure the demo
<VarField name="title" label="Title" persist />
</Step>
Markers are stripped from rendered and downloaded code. Broken references fail the build with the file and line, so tutorials don't rot silently.
Examples
Built a tutorial with it? Add it to the showcase.
Documentation
On the website, with search. The source is docs/.
- Quick start — from zero to a published tutorial
- Features — everything the tool can do, in one page
- Authoring reference — how a tutorial works, folder structure, frontmatter, components, code markers, build errors
- Presenting a tutorial — presentation mode, clickers, zoom and offline fallback for talks
- CLI reference — the project wizard,
dev, build, serve, check, skills install, doctor and init-scripts
- Deployment — GitHub Pages and other static hosts
- Upgrade guide
🧪 Beta, and evolving fast
InteractiveCodeScroll is in beta: it is used for real tutorials and talks, and authoring APIs may still change before 1.0 (the upgrade guide covers every breaking change).
The first beta was built in under a week, driven by the needs of real tutorials — and it can keep moving at that pace with yours. Missing something? Found a bug? Open an issue. Ideas from people who teach are what shape the roadmap.
If it looks useful, a ⭐ helps others find it.
Transparency
- Built with AI coding agents. Design decisions, reviews and releases are human-led; most of the code and docs were written with AI agents (Claude Code and Codex). The agent instructions are in the repo: CLAUDE.md, AGENTS.md, and the specification in docs/dev/SPEC.md.
- Inspired by Stripe's interactive quickstarts.
- Stack: Astro, MDX, Shiki, Calcite Design System, Vitest and Playwright.
- Not an official Esri product. A personal open-source project by @hhkaos. The core is topic-agnostic; ArcGIS appears only in example tutorials.
Contributing
Bug reports, ideas, docs fixes and code are all welcome. Start with CONTRIBUTING.md. Please follow the Code of Conduct and report vulnerabilities as described in SECURITY.md.
License
Apache-2.0
