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
npm create interactive-code-scroll@latest my-tutorial
cd my-tutorial
npm run devThe 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 and whether to add a GitHub Pages workflow. It writes a working example you can edit right away.
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.
| 🧭 Scroll-synced steps | Each step focuses a file, a code region or an image carousel. Deep links to any step. |
| 🎤 Presentation mode | Clean, projector-friendly layout. Keyboard and clicker (PageUp/PageDown) navigation. |
| 🌐 Multi-language variants | One tutorial, several languages (e.g. cURL / Python / JavaScript). Readers switch in place. |
| Web code runs in an embedded Preview, with an "open in new tab" fallback. | |
| 📡 Request runner | .http requests run from the page; captured output shows when there is no token. 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. |
| 📚 Series sites | Many tutorials in one site, with an index, tag filters 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 docs/features.md.
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 configMDX 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.
- Geocode an address with the ArcGIS REST API — cURL, Python and JavaScript variants, live requests, captured output and error explanations.
- OAuth PKCE with the ArcGIS Maps SDK for JavaScript — user authentication with a live Preview.
Built a tutorial with it? Add it to the showcase.
- Quick start — from zero to a published tutorial
- Features — everything the tool can do, in one page
- Authoring and API reference — folder layout, frontmatter, components, code markers
- CLI reference —
create,dev,build,serve,doctor - Deployment — GitHub Pages and other static hosts
- Upgrade guide
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.
- 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.
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.