Code walkthrough

A tutorial often shows the same file several times, with a few lines more each time. Readers must compare the blocks line by line to find the change. A code walkthrough puts the versions in one block with numbered steps in the title bar. When the reader changes step, unchanged code moves to its new place, and new code fades in.

Good for:

A file that grows over a few steps, where each step needs only a short label. The versions take the space of one block, and readers step through them with buttons. To explain each step in paragraphs next to the code, use scrollycoding.

Readers see

server.js123Create the app

const app = express();

app.listen(3000);

‹PreviousStep 1 of 3Next›

server.js123Parse JSON bodies

const app = express();
app.use(express.json());

app.listen(3000);

‹PreviousStep 2 of 3Next›

server.js123Add a health route

const app = express();
app.use(express.json());

app.get('/health', (req, res) => {
  res.json({ ok: true });
});

app.listen(3000);

‹PreviousStep 3 of 3Next›

You write

<CodeWalkthrough>

```js title="server.js" step="Create the app"
const app = express();

app.listen(3000);
```

```js title="server.js" step="Parse JSON bodies"
const app = express();
app.use(express.json());

app.listen(3000);
```

```js title="server.js" step="Add a health route"
const app = express();
app.use(express.json());

app.get('/health', (req, res) => {
  res.json({ ok: true });
});

app.listen(3000);
```

</CodeWalkthrough>

Click Next, and app.listen(3000); moves down while the new line fades in. Each numbered step shows one version of the file. The label of the current step shows next to the numbers.

Syntax

Syntax	Where
<CodeWalkthrough> … </CodeWalkthrough>	Around the code blocks, in an MDX file
step="<label>"	Code block fence line of each step

Import the component at the top of the MDX file:

import { CodeWalkthrough } from 'starlight-codeblocks/components';

Put two or more code blocks between the tags, with an empty line after <CodeWalkthrough> and before </CodeWalkthrough>. Each code block is one step, in order. The step attribute is optional. Each step keeps its other attributes, such as title.

Examples

Steps without a title

A configuration file grows one section at a time. The steps have no titles, so the title bar shows the steps only:

Output

12Name the site

site:
  name: Example Docs

‹PreviousStep 1 of 2Next›

12Add a search index

site:
  name: Example Docs
search:
  index: true

‹PreviousStep 2 of 2Next›

Source

<CodeWalkthrough>

```yaml step="Name the site"
site:
  name: Example Docs
```

```yaml step="Add a search index"
site:
  name: Example Docs
search:
  index: true
```

</CodeWalkthrough>

A refactor

A refactor changes the code inside a function. Code that stays moves to its new place, so readers see the loop become one call to sum():

Output

prices.py12Before

def total(items):
    result = 0
    for item in items:
        result += item.price
    return result

‹PreviousStep 1 of 2Next›

prices.py12With sum()

def total(items):
    return sum(item.price for item in items)

‹PreviousStep 2 of 2Next›

Source

<CodeWalkthrough>

```py title="prices.py" step="Before"
def total(items):
    result = 0
    for item in items:
        result += item.price
    return result
```

```py title="prices.py" step="With sum()"
def total(items):
    return sum(item.price for item in items)
```

</CodeWalkthrough>

Behaviour

• The controls:
  • The title bar shows the title, the numbered steps and the label of the current step.
  • Earlier steps have an outline in the accent colour. The current step is filled.
  • When the mouse cursor is on a step, its border changes colour. This is true for earlier steps and the current step too.
  • A row under the block shows the Previous and Next buttons, with the step count between them, such as “Step 2 of 3”.
  • When the steps are narrower than 480 px, the label is hidden. If the label is too long for the title bar, it ends with an ellipsis.
• Moving between steps:
  • Click a number to go to that step. You cannot click Previous on the first step, or Next on the last step.
  • When a numbered step has keyboard focus, the left and right arrow keys go to the previous and the next step.
• Screen readers:
  • Screen readers announce the number and the label of the new step.
  • The name of each numbered step gives the label to screen readers, also when the label is hidden.
• Copy and print:
  • The copy button copies the code of the current step.
  • The numbered steps and the row of Previous and Next buttons do not print. Each step prints in order, with its label.
• Without JavaScript:
  • Each step shows as a separate code block, in order, with its label after the title.
• Motion:
  • The animation takes 480 ms. Code that is in both versions moves. Removed code fades out, and new code fades in.
  • A line that is new in the step gets a green tint, which fades out in 1 second. The green is the terminal green of the theme.
  • When the reader’s system asks for reduced motion, the steps change without the animation.

Options

Code walkthrough has no options. To turn the feature off for the whole site, set walkthrough to false:

astro.config.mjs

codeblocks({
  walkthrough: false,
});

With walkthrough: false, <CodeWalkthrough> shows each step as a separate code block with its label after the title, as it does without JavaScript. The page loads no script for the steps.

The style settings in the codeblocksWalkthrough group change the colours of the steps and the length of the animation. For example, codeblocksWalkthrough.duration sets the length of the animation, and codeblocksWalkthrough.newLineBackground sets the tint of new lines.

ConfigurationLearn how to set options for the whole site, or for a single code block.

Limitations

• <CodeWalkthrough> works in MDX files only, because Markdown files cannot contain components.
• During the animation, the block shows the syntax colours only. Line numbers, line states and other decorations show again when the animation ends.
• A jump over several steps animates from the first version to the last. Code that exists in both only through a middle step fades out and in again.
• The page loads the animation library, about 3 kB, only on pages with <CodeWalkthrough>.

Related

• Scrollycoding: prose steps that change the focus of a block, and can change its code, as the reader scrolls.
• Word-level diff: one block that marks the changed words between two versions.
• Code tabs: versions that are alternatives, such as package managers, and not steps in an order.