Quick Start
Build and publish your first interactive tutorial in a few minutes.
1. Create a project
Section titled “1. Create a project”npm create interactive-code-scroll@latest my-tutorial# or: pnpm create interactive-code-scroll@latest my-tutorialThe wizard asks for one tutorial or a series, what each tutorial uses (web app, REST API, script, native app and their languages), the package manager and whether to add a GitHub Pages workflow. Every answer has a flag, and --yes takes the defaults; see Create a Project.
Then start the dev server:
cd my-tutorialnpm run devOpen the URL it prints. Edits to tutorial.mdx and the files in code/ reload the page, and broken references show an error overlay with the file and line.
2. Know the folder structure
Section titled “2. Know the folder structure”tutorial/ tutorial.mdx # the explanations: frontmatter + <Step> blocks code/ # runnable source files shown in the code panel images/ # optional screenshots and diagramsSeries sites use tutorials/<name>/ with the same structure per tutorial. REST and script tutorials add requests/ (.http files the reader can run) and output/ (captured results). See the authoring reference for every option.
3. Mark your code
Section titled “3. Mark your code”Your source files stay plain and runnable. Comments in the file’s own syntax mark the regions a step focuses on, and @var marks string literals readers can edit:
// #region configconst title = "My first tutorial"; // @var title// #endregion configMarkers are stripped from the rendered code, the Preview and the downloads.
4. Write the steps
Section titled “4. Write the steps”The frontmatter configures the page; <Intro> holds the context before the first step; each <Step> points at a file and region:
---title: My first tutorialpreview: both # embedded Preview + "open in new tab"theme: auto---
<Intro>
## What you will build
A short page that greets the reader.
</Intro>
<Step id="configure" file="main.js" region="config">
## Configure the demo
Change the title: the code, the Preview and the downloads update in place.
<VarField name="title" label="Title" persist />
</Step>Steps reference ids, never line numbers, so editing the code does not break them. A step can also show images (images={["diagram.png"]}), a captured output (output="result.json") or a runnable request (request="get-items").
For extra context, use <Hint> for inline popovers, Markdown blockquotes for notes and <details> for optional explanations.
5. Build and publish
Section titled “5. Build and publish”npm run build # static site in dist/npm run serve # check the built site locallyIf you chose the GitHub Pages workflow, push to GitHub and enable Settings → Pages → Source: GitHub Actions; every push to the default branch publishes the site. For other hosts and base paths, see Deployment.
Use a coding agent
Section titled “Use a coding agent”The package ships Agent Skills that teach a coding agent (Claude Code, GitHub Copilot and others) how this tool works, so it does not have to read these docs first:
ics-authoring: the project layout, components, frontmatter, code markers, panes, variants and series, and the CLI.ics-verify: the validation loop oninteractive-code-scroll check --json, then a build.ics-tutorial-design,ics-tutorial-review,ics-talkandics-migrate: plan a tutorial, review a draft, prepare it for a talk, and convert a blog post or codelab (or upgrade). See Agent Skills.
Pick your agents when you create the project (the wizard asks, or --agents claude,copilot,agents): it adds a skills script, an AGENTS.md and, for Claude Code, a CLAUDE.md. In an existing project, copy the skills into your agent’s folder from the installed version:
npx interactive-code-scroll skills install --agent claude # or copilot, agents, allThen ask for what you want, for example “plan a 10-minute demo of this API”, “add a step that explains the config region”, “turn this blog post into a tutorial” or “review the tutorial before my talk”. Run it again after upgrading the package. See Coding Agents for the skills, what to ask and the validation loop. The same skills are in the repository’s skills/ folder.
Next steps
Section titled “Next steps”- Coding agents — build tutorials with Claude Code, GitHub Copilot or another agent
- Features — everything the tool can do
- Authoring reference — frontmatter, components, markers, validation rules
- CLI reference —
dev,build,serve,check,doctorand their options