Skip to content

Split diff

Expressive Code shows a diff block in one column, with each removed line above the line that replaces it. Split diff adds a switch with Unified and Split buttons to the title bar of each block that removes and adds lines. Split shows the old code on the left and the new code on the right, as a pull request on GitHub does.

Readers see

server.js
import express from 'express';
const app = express();
app.listen(3000);
const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => {
console.log(`Listening on port ${port}`);
});

You write

```diff lang="js" title="server.js"
import express from 'express';
const app = express();
-app.listen(3000);
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => {
+ console.log(`Listening on port ${port}`);
+});
```

Click Split in the example. The unchanged lines show on both sides. The removed line is next to the first added line, and a shaded cell fills the left side of the other added lines.

Syntax Where
A diff block Code block fence line
ins={range}, del={range} Code block fence line
[!code ++], [!code --] Comment
splitDiff.view="unified", splitDiff.view="split" Code block fence line
splitDiff.switch=false Code block fence line
splitDiff.sync=false Code block fence line
splitDiff=false Code block fence line

Each block that has a removed line and an added line, from any of these sources, gets the switch. You do not turn it on. splitDiff=false turns the feature off for one block, the same as splitDiff.switch=false in the unified view.

[!code --] and [!code ++] give the same split view, without changing the language of the block:

config.py
DEBUG = False
TIMEOUT = 30
RETRIES = 3
TIMEOUT = 60
RETRIES = 5

splitDiff.view="split" starts a block in the split view. A block without a title gets a small title bar for the switch. splitDiff.sync=false makes the switch change only this block, so the reader’s choice on other blocks does not change it:

const res = await fetch(url);
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
const data = await res.json();

splitDiff.switch=false removes the switch, so the block always shows its view. Use it for a block that only makes sense side by side:

docker-compose.yml
services:
web:
image: nginx:1.25
image: nginx:1.27
ports:
- "80:80"
- "8080:80"
Section titled “In a code walkthrough, with line permalinks”

Each step of a code walkthrough can be a diff. Here each step shows the change so far against the same file, and the switch changes every step. With id, line permalinks turn the line numbers into links. In the split view, each side counts its own lines, and each link still opens its line:

server.jsRead the port
const app = express();
app.listen(3000);
const port = Number(process.env.PORT ?? 3000);
app.listen(port);
Step 1 of 2
server.jsLog the port
const app = express();
app.listen(3000);
const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => {
console.log(`Listening on port ${port}`);
});
Step 2 of 2
  • Switching the view:
    • By default, the switch changes every diff block on the page at once. Blocks with splitDiff.sync=false or with no switch keep their view.
    • The browser remembers the choice, so synced blocks on the next page open in the same view. Before the reader makes a choice, each block starts in its splitDiff.view.
    • Screen readers announce the button of the current view as pressed.
  • Layout:
    • Unchanged lines show on both sides. Removed lines show on the left, and added lines show on the right.
    • The plugin pairs a run of removed lines with the run of added lines below it, one by one. A shaded cell fills the side of a line that has no pair.
    • With line numbers, from Expressive Code or from line permalinks, the left side counts the lines of the old code. The right side counts the lines of the new code.
    • Both sides have the same width. A long line wraps inside its side, as on GitHub.
  • Copy and screen readers:
    • The copy button copies the same text in both views.
    • Screen readers read the block as a unified diff in both views. They skip the copies of the unchanged lines on the right.
  • Without JavaScript:
    • The switch does not show, and every block shows the unified view, also with splitDiff.view="split".

Adds a switch to diff blocks that shows the old code and the new code side by side. Set it to false to turn the feature off.

Type
false | object
Default
On

The view that each diff block starts in. A code block can set its own on its fence line.

Type
'unified' | 'split'
Default
'unified'

Shows the Unified and Split switch. With false, each block stays in its view. A code block can set its own on its fence line.

Type
boolean
Default
true

The switch changes every synced block on the page, and the browser remembers the choice. With false, each block switches alone. A code block can set its own on its fence line.

Type
boolean
Default
true

To start every diff block in the split view, and let each block switch alone, set both for the site:

astro.config.mjs
codeblocks({
splitDiff: { view: 'split', sync: false },
});
  • Pairing is by position, as in word-level diff. A block that adds or removes a different number of lines can pair the wrong lines.
  • You cannot select the text of the unchanged lines on the right. Select them on the left.
  • Features that light a line when the reader acts, such as code mentions, light the left copy of an unchanged line only. Line permalinks light both sides.
  • A block with collapsible sections (collapse) gets no switch.
  • Word-level diff: highlight the changed words inside each pair of lines, in both views.
  • Code walkthrough: show code that changes in steps, instead of as a diff.