Upgrade Guide
InteractiveCodeScroll is still pre-v1. Keep upgrades deliberate and test each tutorial after changing versions.
Panel API migration (0.2.0-beta.10)
Section titled “Panel API migration (0.2.0-beta.10)”Step and intro preview= has been replaced by view (select and open) and collapsed (visibility). Frontmatter preview: off|iframe|tab|both is unchanged: both still means iframe plus a new-tab button.
| Before | After |
|---|---|
preview="expanded" on a web step/intro |
view="preview" |
preview="expanded" on a non-web step/intro |
view="result" |
preview="collapsed" |
collapsed |
preview="keep" |
Omit view and collapsed. |
maximize="preview" |
maximize="panel" |
If you tried the unreleased panel API, replace panel="preview|console|result" with the corresponding view and panel="collapsed" with collapsed.
Console is optional and off by default. Set frontmatter console: true with preview: iframe or both to add Preview / Console tabs and capture live messages; then use view="console" on a step to open Console. Without that opt-in, only Preview is shown, without tabs or capture. Existing console demonstrations need the new frontmatter opt-in.
view selects and opens a view; collapsed folds the whole pane; collapsed={false} opens it without switching views. Do not combine view with collapsed set to true. In mixed-variant tutorials, a view applies to variants that have that pane. Omit both props to preserve the reader’s current state. Old step/intro attributes fail validation with migration guidance. See Panel and Console.
Other usage changes in 0.2.0-beta.10
Section titled “Other usage changes in 0.2.0-beta.10”panelHeight={30} on <Step> or <Intro> reserves 30% of the right column for the lower pane (allowed range: 15–85). It does not overwrite the reader’s saved height. Omit it to keep the current size. Opening or resizing the pane now keeps the active code region visible. See Panel and Console.
Read aloud changes (0.2.0-beta.9)
Section titled “Read aloud changes (0.2.0-beta.9)”Read aloud now continues in presentation mode; Alt+Shift+L can start it there. Narration also works with the explanations hidden; Alt+Shift+L starts, pauses or resumes it there. Hints are read as asides after their terms. Current listening controls offer Step by step and Continuous modes; closed <details> sections read only their summaries unless the reader enables Read collapsed sections. No migration is required. To exclude an element, such as a solution, from narration, add data-speech="skip". See Listen to a tutorial.
Recommended Upgrade Flow
Section titled “Recommended Upgrade Flow”- Read the changelog for all changes, including additions, fixes and defaults that affect how you use the library.
- Update
interactive-code-scrollandastrotogether when the release notes ask for it. - Run
interactive-code-scroll doctor. - Run the tutorial in dev mode and fix validation errors.
- Build the tutorial.
- Check Preview, downloads and any provider-specific flows.
npm install -D interactive-code-scroll astro@7.3.5npm exec -- interactive-code-scroll doctornpm exec -- interactive-code-scroll devnpm exec -- interactive-code-scroll buildAuthoring Changes To Watch
Section titled “Authoring Changes To Watch”- Frontmatter fields: new validation may reject misspelled or unsupported values.
- MDX components: props are intentionally small and explicit.
- Markers: malformed regions and duplicate variables fail the build.
- Preview:
code/index.htmlis required when Preview is enabled. - CLI arguments: package scripts must forward options after
--.
Release notes and compatibility
Section titled “Release notes and compatibility”The changelog records all changes. This guide highlights migration steps and changes to authoring or reader behavior; new optional features belong in the authoring reference and feature guide even when no migration is needed.
Breaking Changes
Section titled “Breaking Changes”Before v1, breaking changes may happen in alpha and beta releases. Each breaking change should include:
- a changelog entry,
- a migration note here,
- an actionable validation error when possible,
- a fixture/E2E case when the behavior is observable through a tutorial.
0.2.0-beta.8: step outline next to the intro
Section titled “0.2.0-beta.8: step outline next to the intro”An <Intro> with no file, images or embed now shows the step outline (the list of steps) in the code area instead of the first file. Set outline: false in the frontmatter (or once in tutorials/index.mdx for a series) to keep the code there. The Back / Next position now opens a step index; step headings are its titles, so keep them short. In presentation mode, Alt+P enters and leaves it, O and E are shortcuts and a lone Alt press lists the keys (Presenting).
0.2.0-beta.7: selection toolbar
Section titled “0.2.0-beta.7: selection toolbar”Selecting text in the explanations or the code now shows a small toolbar to ask about the selection: “Ask the author” (with a feedbackUrl) and “Ask AI” (ChatGPT and Claude). It is on by default. No tutorial changes are needed; to receive the selected text in your issues, add {context} to feedbackUrl (e.g. ...issues/new?title={title}&body={context}). To choose the actions, or add your product’s assistant, set ask per tutorial or in tutorials/index.mdx; ask: false turns the toolbar off.
0.2.0-beta.7: closing panel after the last step
Section titled “0.2.0-beta.7: closing panel after the last step”Every tutorial now ends with a closing panel: at the last step “Next” becomes “Finish” instead of being disabled. The panel offers the code download, the Preview tab and, in a series, the next tutorial (the next one in index order unless you set next) and the index. No tutorial changes are needed. Optionally add an <Outro> with your own closing text and a feedbackUrl (per tutorial, or once for a series in tutorials/index.mdx); check that the suggested next tutorial makes sense in your series, or set next: false. To keep the old ending, set completion: false. In presentation mode the clicker now ends on a closing slide with a QR code of the tutorial; if you present from localhost, set presentationUrl (or Astro site) so it opens the published copy.
0.2.0-beta.6: wider explanations and field rows
Section titled “0.2.0-beta.6: wider explanations and field rows”The explanations no longer cap lines at 70 characters: text uses the panel’s width when the reader widens it. Consecutive <VarField>s are laid out in as many columns as the panel fits; put prose between fields that must stay on their own row. Notes (blockquotes) in inactive steps are now gray, and fenced code blocks follow the light/dark mode with the code panel’s themes unless astro.config.mjs sets markdown.shikiConfig.theme or themes. No tutorial changes are needed; check pages that relied on the old layout.
0.2.0-beta.5: file tab order without files
Section titled “0.2.0-beta.5: file tab order without files”A tutorial (or variant) without frontmatter files now orders its file tabs by the steps: each file in the order a <Step> first shows it, then the rest by path. Before, every tab was in path order. Check your tabs after upgrading; to keep another order, list it in files. See Files Not Shown In Tabs.
0.2.0-beta.5: series cards and custom index pages
Section titled “0.2.0-beta.5: series cards and custom index pages”- Cards no longer show the tutorial logo or variant logos next to the title (the tutorial
logostays for its page header and favicon). Tag and variant logos come fromtagGroupsentries ({ name, logo }) and variantlogos. See Tag families. - Variant labels are now tags of their tutorial:
<TutorialList tags="Python">also lists a tutorial with a Python variant, and the search bar counts and filters them. - Custom index pages:
SeriesCard.variantLogosis gone. Usevariants({ id, label, href, logo }, with two or more variants) andtagLogos(tag → logo URL). <TutorialFilter>is now a search bar (text, tags, level), with no change toindex.mdx. On a custom page it accepts an optionaltagGroupsprop.- New, opt-in:
<TutorialFavorites />. See Index page.
0.2.0-beta.5: <details> spacing
Section titled “0.2.0-beta.5: <details> spacing”Open disclosure blocks now leave a gap below <summary>: remove any inline margin-top you added to the first element. A <summary> that MDX puts inside a paragraph (no blank line before the content) now prints a build warning with its file:line; add the blank lines.
0.2.0-beta.0: latest dist-tag
Section titled “0.2.0-beta.0: latest dist-tag”Releases are no longer published only under @alpha: npm install -D interactive-code-scroll and npm create interactive-code-scroll@latest get this version. Projects pinned to interactive-code-scroll@alpha keep the last alpha until they change the specifier:
npm install -D interactive-code-scroll@latest astro@7.3.50.2.0-beta.0: one default per variable name
Section titled “0.2.0-beta.0: one default per variable name”A variable name used in several files must now have the same default literal everywhere. Before, the form field silently took the first file’s default. The build now fails with @var "name" must have the same default in every file: … listing each file and value.
Fix it by using the same demo value in every file, or by giving the variables different names.
0.2.0-beta.0: clicker keys from fields and the Result pane
Section titled “0.2.0-beta.0: clicker keys from fields and the Result pane”PageDown/PageUp now move steps even while the focus is in a form field, the JSON tree or the Result pane (only multi-line text keeps them), so presentation clickers work after typing a value. Arrow keys are unchanged in fields and the JSON tree, and the Result pane’s Body/Headers tabs and “Run as” picker now keep their arrow keys too. No tutorial changes are needed.
0.2.0-beta.0: results and requests (multi-SDK Phase 1)
Section titled “0.2.0-beta.0: results and requests (multi-SDK Phase 1)”New optional folders and props: output/ with <Step output="…">, requests/ (.http files and errors.json) with <Step request="…">, variants in the frontmatter, <Step only="…"> and otherVariantSteps. Existing tutorials build unchanged unless they hit one of these new build errors:
output=orrequest=on a step that only web code shows (web code has the Preview).- A
code/requests/folder (orcode/<variant dir>/requests/) in a tutorial withrequests/: both would land in the ZIP asrequests/. Rename the code folder. - With
variants, every file undercode/must be in exactly one variant folder, and the top-levelfiles:moves into each variant.
See Result Pane, HTTP Requests and Code Variants.
0.2.0-beta.0: literals that cannot be escaped
Section titled “0.2.0-beta.0: literals that cannot be escaped”@var on a Python f-string, raw string or triple-quoted string, or on a TOML literal string ('...'), is now a build error because typed values could break the code. Switch the literal to a plain string.