.*?b<\/span>/);
+ const numbered = await render(block('js showLineNumbers', 'a();', '// [!code skip]', 'b();'), {}, [
+ pluginLineNumbers(),
+ ]);
+ expect(skipLines(numbered.html)).toEqual([expect.stringMatching(/class="ln"[^>]*>2)]);
+ const end = await render(block('js', 'a();', '// [!code skip] More'));
+ expect(end.html).toMatch(/>a<.*scb-skip-line.*More<\/span><\/span><\/div><\/div><\/code>/);
+});
+
+test('hides a [!code skip] line in a hidden run with the run', async () => {
+ const { html } = await render(block('js hidden={2-4}', 'a();', 'b();', '// [!code skip] Inside', 'c();', 'd();'));
+ expect(skipLines(html)).toEqual([expect.stringContaining('scb-skip-line scb-hidden-line scb-no-print')]);
+});
+
+test('warns about a [!code skip] on a line with code, with a count, or in output', async () => {
+ const { html, warnings } = await render(block('js', 'a(); // [!code skip]', '// [!code skip:2]', 'b();'));
+ expect(skipLines(html)).toEqual([]);
+ expect(warnings).toEqual([
+ expect.stringContaining('goes on a line of its own'),
+ expect.stringContaining('`[!code skip:2]` takes no count'),
+ ]);
+ const output = await render(block('sh', 'make', '# [!output]', 'built', '# [!code skip]'));
+ expect(output.warnings).toEqual([expect.stringContaining('is not in the code, so it shows as a comment')]);
+});
+
+test('keeps a [!code skip] line before [!output] in the code', async () => {
+ const { html, warnings } = await render(block('sh', 'make', '# [!code skip] More', '# [!output]', 'built'));
+ expect(warnings).toEqual([]);
+ expect(skipLines(html)).toEqual([expect.stringContaining('More')]);
+});
+
+test('keeps the diff prefix and indentation of a [!code skip] line', async () => {
+ const short = await render(block('diff lang="js"', ' function f() {', '+ // ...', '+ return 1;', ' }'));
+ expect(skipLines(short.html)).toEqual([expect.stringContaining('
+ {
+ const js = await render(block('js', 'function connect() {', ' // ...', ' return socket;', '}'));
+ const directive = await render(block('js', 'function connect() {', ' // [!code skip]', ' return socket;', '}'));
+ expect(js.html).toBe(directive.html);
+ const json = await render(block('json', '{', ' "a": 1,', ' ...', '}'));
+ expect(skipLines(json.html)).toHaveLength(1);
+ expect(json.copyText).toBe('{\n "a": 1,\n ...\n}');
+ expect(json.warnings).toEqual([]);
+});
+
+test('leaves `...` with no alias for its language, or with more text, as written', async () => {
+ for (const md of [
+ block('py', 'def f():', ' ...'),
+ block('yaml', 'a: 1', '...'),
+ block('js', 'f(...args) // ...', '// ... more', '// [...]', '...'),
+ block('json', '[', ' "..."', ']'),
+ ]) {
+ expect(skipLines((await render(md)).html)).toEqual([]);
+ }
+});
+
+test('takes aliases by language, with `*` for the others, merged over the defaults', async () => {
+ const skippedCode = { commentAliases: { '*': ['…'], py: [] }, bareAliases: { yml: ['...'] } };
+ const lines = async (md: string) => skipLines((await render(md, { skippedCode })).html).length;
+ expect(await lines(block('js', 'a();', '// …', '// ...', 'b();'))).toBe(1);
+ expect(await lines(block('py', 'a()', '# …'))).toBe(0);
+ expect(await lines(block('yaml', 'a: 1', '...', '# …'))).toBe(2);
+ expect(await lines(block('json', '{', ' ...', '}'))).toBe(1);
+ const custom = await render(block('js', 'a();', '// …', 'b();'), { skippedCode });
+ expect(custom.copyText).toBe('a();\n// …\nb();');
+});
+
+test('renders as without the feature when a block skips nothing, and leaves the directive when it is off', async () => {
+ const md = block('js title="a.js" {1}', 'a()', 'b()');
+ expect((await render(md)).html).toBe((await render(md, { skippedCode: false })).html);
+ const { copyText, warnings } = await render(block('js', 'a() // [!code skip]'), { skippedCode: false });
+ expect(copyText).toBe('a() // [!code skip]');
+ expect(warnings).toHaveLength(1);
+});
+
+test('keeps the line state message of a [!code skip] line', async () => {
+ const { html } = await render(block('js', 'a();', '// [!code warn] Careful', '// [!code skip]', 'b();'));
+ expect(skipLines(html)).toEqual([
+ 'Warning:// ...Code not shownWarning Careful
',
+ ]);
+});
+
+test('reads no diff prefix in a line that the diff syntax already shortened', async () => {
+ const { html, warnings } = await render(block('diff lang="yaml"', ' a:', ' - # [!code highlight]', '+ b: 1'));
+ expect(html).not.toContain('[!code');
+ expect(warnings).toEqual([]);
+});
+
+test('gives no warning for an alias in output, and leaves it as written', async () => {
+ const sh = await render(block('sh', 'make', '# [!output]', 'built', '# ...'));
+ expect(sh.warnings).toEqual([]);
+ expect(sh.copyText).toBe('make');
+ expect(sh.html).toContain('# ...');
+});
+
+test('gives the text of a dropped [!code skip] to the next directive that takes text', async () => {
+ const { html, warnings } = await render(block('js', 'a(); // [!code skip error] Bad call'));
+ expect(skipLines(html)).toEqual([]);
+ expect(html).toMatch(/scb-state-label[^>]*>.*Bad call/);
+ expect(warnings).toEqual([expect.stringContaining('goes on a line of its own')]);
+});
+
+test('reads the comment of a [!code skip] line as its tokens', async () => {
+ const { html } = await render(block('js', 'a();', ' // [!code skip]', 'b();'));
+ const tree = fromHtml(html, { fragment: true });
+ markDecorations(tree);
+ expect(readTokens(tree as never).code).toBe('a();\n // ...\nb();');
+});
diff --git a/packages/starlight-codeblocks/test/styles.test.ts b/packages/starlight-codeblocks/test/styles.test.ts
index dbc8524..893cbbb 100644
--- a/packages/starlight-codeblocks/test/styles.test.ts
+++ b/packages/starlight-codeblocks/test/styles.test.ts
@@ -29,6 +29,7 @@ test('muted text meets 4.5:1 on the tinted surfaces it sits on', async () => {
const bg = get('codeBackground');
const surfaces = [
get('codeblocksHiddenLines.badgeBackground'),
+ get('codeblocksSkippedCode.badgeBackground'),
mix(bg, get('codeForeground'), 0.05),
getFirstStaticColor(get('frames.editorTabBarBackground')),
];
diff --git a/scripts/readme-media.mjs b/scripts/readme-media.mjs
index 847bc51..c1f51ce 100644
--- a/scripts/readme-media.mjs
+++ b/scripts/readme-media.mjs
@@ -67,6 +67,7 @@ const features = [
await rec.hold(1000);
},
},
+ { slug: 'skipped-code' },
{
slug: 'smart-shell-copy',
run: async (page, rec) => {
diff --git a/skills/starlight-codeblocks/SKILL.md b/skills/starlight-codeblocks/SKILL.md
index d445039..9acb4b1 100644
--- a/skills/starlight-codeblocks/SKILL.md
+++ b/skills/starlight-codeblocks/SKILL.md
@@ -1,12 +1,12 @@
---
name: starlight-codeblocks
-description: Write, choose and configure code block features on Astro Starlight sites that use the starlight-codeblocks plugin. Covers focus, line states, squiggles, comment notation directives, annotations, footnotes, inline callouts, side annotations, scrollycoding, code mentions, word-level diff, split diff, code walkthrough, hidden lines, expandable blocks, visible whitespace, colourised brackets, colour swatches, file icons, inline code highlighting, code links, API auto-linking, line permalinks, code tabs, fill-in placeholders, smart shell copy, open in playground and run code. Use when you install or configure starlight-codeblocks, when you write or edit code blocks in .md, .mdx or .mdoc pages of a site that has it, when you add these features to the existing pages of a site, or when you must choose how to explain, highlight, compare, shorten, link or run code in Starlight docs.
+description: Write, choose and configure code block features on Astro Starlight sites that use the starlight-codeblocks plugin. Covers focus, line states, squiggles, comment notation directives, annotations, footnotes, inline callouts, side annotations, scrollycoding, code mentions, word-level diff, split diff, code walkthrough, hidden lines, skipped code, expandable blocks, visible whitespace, colourised brackets, colour swatches, file icons, inline code highlighting, code links, API auto-linking, line permalinks, code tabs, fill-in placeholders, smart shell copy, open in playground and run code. Use when you install or configure starlight-codeblocks, when you write or edit code blocks in .md, .mdx or .mdoc pages of a site that has it, when you add these features to the existing pages of a site, or when you must choose how to explain, highlight, compare, shorten, link or run code in Starlight docs.
license: MIT
---
# starlight-codeblocks
-starlight-codeblocks is a Starlight plugin. It adds 28 features to the code blocks that Expressive Code renders. A feature starts only when a code block uses its attribute or its directive, so the plugin does not change existing pages. A few features apply to every block of a type: they are in [Features that start on their own](#features-that-start-on-their-own).
+starlight-codeblocks is a Starlight plugin. It adds 29 features to the code blocks that Expressive Code renders. A feature starts only when a code block uses its attribute or its directive, so the plugin does not change existing pages. A few features apply to every block of a type: they are in [Features that start on their own](#features-that-start-on-their-own).
Full docs: https://ewels.github.io/starlight-codeblocks/. Each page has a Markdown version at the same address with `.md` at the end. https://ewels.github.io/starlight-codeblocks/llms-full.txt has every page in one file.
@@ -77,6 +77,7 @@ Use scrollycoding when prose explains the code step by step as the reader scroll
| Goal | Use | Why |
|---|---|---|
| Imports and set-up that readers need to run the code but not to understand it | Hidden lines: `hidden={1-3}` or `[!code hide]` | Named lines go behind a marker. The copy button still copies them. |
+| Code that the example leaves out, where authors write `// ...` | Skipped code: `[!code skip]`, or `// ...`, which is an alias by default | The line shows as a marker and copies as a comment. The copied code is incomplete. |
| A long file that readers scan | Expandable block: `expandable` or `expandable={N}` | Shows the first lines, with a button that shows the rest. |
| Indentation or tabs change the meaning (Make, Python, YAML) | Visible whitespace: `whitespace` or `whitespace="all"` | Shows spaces and tabs as faint glyphs. |
| Deep nesting on dense lines | Colourised brackets: `brackets` | Colours bracket pairs by depth. |
@@ -165,6 +166,7 @@ These features need no attribute. Know them, because they can change a block tha
- File icons apply to every block with a title in an editor frame. Turn them off for a block with `icon=false`, or for a file type or a language with `false` in `fileIcons.files` or `fileIcons.languages`.
- Expandable blocks apply to every block longer than `expandable.auto` lines, if the site sets that option. Turn it off for a block with `expandable=false`.
- Inline code highlighting applies to all inline code, if the site sets `inlineHighlighting.defaultLanguage`. Keep one piece plain with `{:txt}`.
+- Skipped code reads every comment that holds only `...`, such as `// ...` or `# ...`, as a marker by default. It also reads `...` alone on its line in JSON. `skippedCode.commentAliases` and `skippedCode.bareAliases` change these per language. Only the look of those lines changes: they keep their line numbers and copy as written. To keep `// ...` as code in one block, add text to the comment, such as `// ... and so on`.
If a page shows one feature, keep the others out of its examples with these attributes.
@@ -175,7 +177,7 @@ If a page shows one feature, keep the others out of its examples with these attr
- For inline code highlighting, put the suffix inside the backticks: `` `res.ok{:js}` ``. MDX reads `` `res.ok`{:js} `` as a JavaScript expression and the build fails.
- A directive with an unknown name, or of a feature that is off, stays in the code and logs a build warning. So does a directive outside a comment that the block's language reads. Read the build warnings after every change: each gives the file, the block and the line.
- Each `id` for line permalinks must be unique on the page, and must not match a heading id.
-- Hidden lines still run in the copied code, in playgrounds and with `runnable`. Code for a playground or the **Run code** button must be complete.
+- Hidden lines still run in the copied code, in playgrounds and with `runnable`. Code for a playground or the **Run code** button must be complete, so it cannot use `[!code skip]`.
- Fill-in placeholder values stay in the browser's `localStorage` by default. For secrets such as API tokens, set `placeholders: { storage: 'session' }`.
- In Markdoc (`.mdoc`) files, put attributes in a `meta` attribute: `` ```js {% meta="focus={2}" %} ``. Code tabs and inline code highlighting do not work there.
- The `` component of Starlight gets every feature inside a block. Give the attributes in its `meta` prop.
diff --git a/skills/starlight-codeblocks/references/configuration.md b/skills/starlight-codeblocks/references/configuration.md
index f3edb4c..0a9af90 100644
--- a/skills/starlight-codeblocks/references/configuration.md
+++ b/skills/starlight-codeblocks/references/configuration.md
@@ -16,7 +16,7 @@ codeblocks({
});
```
-To turn on only some features, list their keys in `only`. Every other feature is then off. A feature that reads directives in comments also turns on `notation`, unless `notation: false`. These are focus, line states, callouts, squiggles, annotations, footnotes, hidden lines, code links, code mentions and run code. Settings for a feature that is not in `only` stop the build.
+To turn on only some features, list their keys in `only`. Every other feature is then off. A feature that reads directives in comments also turns on `notation`, unless `notation: false`. These are focus, line states, callouts, squiggles, annotations, footnotes, hidden lines, skipped code, code links, code mentions and run code. Settings for a feature that is not in `only` stop the build.
```js
codeblocks({ only: ['focus', 'codeTabs'], codeTabs: { control: 'menu' } });
@@ -32,6 +32,7 @@ codeblocks({ only: ['focus', 'codeTabs'], codeTabs: { control: 'menu' } });
| `annotations` | `style`: `'filled'` or `'outline'`, default `'filled'` | Annotations and side annotations |
| `footnotes` | `sticky`: default `false`. `style`: `'filled'` or `'outline'`, default `'outline'` | Footnotes |
| `hiddenLines` | None | Hidden lines |
+| `skippedCode` | `commentAliases`: comments that are the same as `[!code skip]`, by language, with `*` for the others, default `{ '*': ['...'] }`. `bareAliases`: lines with no comment, default `{ json: ['...'] }`. Keys merge over the defaults; `[]` turns a language off | Skipped code |
| `shellCopy` | `prompts`: default `['$ ', '> ']`. Python `>>>` sessions need no prompt setting | Smart shell copy |
| `wordDiff` | `minSimilarity`: from 0 to 1, default `0.4` | Word-level diff |
| `splitDiff` | `view`: `'unified'` or `'split'`, default `'unified'`. `switch`: default `true`. `sync`: default `true` | Split diff |
diff --git a/skills/starlight-codeblocks/references/explain-code.md b/skills/starlight-codeblocks/references/explain-code.md
index 5a81ca1..2e820c4 100644
--- a/skills/starlight-codeblocks/references/explain-code.md
+++ b/skills/starlight-codeblocks/references/explain-code.md
@@ -191,7 +191,7 @@ app.listen(3000);
- Leave an empty line after `` and before ``. Each code block is one step, in order. Each keeps its other attributes, such as `title`.
- The walkthrough opens on its first step. For a Before and After pair, put Before first and add `start="last"`: the reader sees and copies After, and **Next** animates the change. `start="2"` in quotes works too. Any other value, or a number outside the steps, logs a build warning and opens the first step.
- The copy button copies the code of the current step.
-- Arrow keys move between steps when a numbered step has focus. Under reduced motion, steps change without the animation. A step with removed or added lines also changes without it, so the diff colours stay.
+- Arrow keys move between steps when a numbered step has focus. Under reduced motion, steps change without the animation. A step with removed or added lines also changes without it, so the diff colours stay. So does a step with a callout or a hidden lines marker.
- A line that is new in a step flashes the theme's green, then fades out in 1 second. There is no flash under reduced motion.
- Without JavaScript, and when the page prints, each step shows as a separate block with its label after the title.
- The page loads the animation library, about 3 kB, only on pages with ``.
diff --git a/skills/starlight-codeblocks/references/readability.md b/skills/starlight-codeblocks/references/readability.md
index fefe8c2..8b312ef 100644
--- a/skills/starlight-codeblocks/references/readability.md
+++ b/skills/starlight-codeblocks/references/readability.md
@@ -3,6 +3,7 @@
Seven features make a block, or the code in the prose, easier to read. None of them changes the copied text.
- If lines are needed to run the code but not to understand it, hide them with hidden lines.
+- If the example leaves code out, mark the place with skipped code, in place of a `// ...` comment.
- If the whole file matters but readers scan it, cap it with an expandable block.
- If every line matters but a few matter more, use focus, in [draw-attention.md](draw-attention.md).
- If the exact whitespace changes the meaning, show it with visible whitespace.
@@ -38,6 +39,34 @@ createServer(handler).listen(port);
- Option: `hiddenLines: false` ignores `hidden` and leaves `[!code hide]` in the code.
- Expressive Code's `collapse={range}` comes from `@expressive-code/plugin-collapsible-sections`. It keeps a summary line for each section and works without JavaScript. Hidden lines take only a thin marker, have a directive and a show-all button, and need JavaScript to open. The docs compare them: https://ewels.github.io/starlight-codeblocks/features/hidden-lines/#hidden-lines-or-collapsible-sections
+## Skipped code
+
+Docs: https://ewels.github.io/starlight-codeblocks/features/skipped-code/
+
+Use where an example shows part of a file and leaves code out. The `// ...` line shows as a marker, so readers do not read it as code. Use hidden lines instead if the copied code must run.
+
+| Syntax | Where |
+|---|---|
+| `[!code skip]` | Comment on its own line where the code is left out |
+| `[!code skip] text` | The same, with `text` on the marker in place of "Code not shown" |
+
+```js
+app.get('/users', async (req, res) => {
+ // [!code skip] Not shown: Read the users from the database
+});
+// [!code skip]
+```
+
+- The marker is a dotted rule with a badge, at the indentation of the directive line. It is not a button.
+- The marker is a line of the block: it has a line number, and line ranges count it.
+- The copied code has the marker as a comment: `// text`, or `// ...` without text. It has no skipped code. Do not use it in a block with a playground or the **Run code** button.
+- On a line with code, or with a count (`:N`), the directive logs a warning and does nothing.
+- Aliases: lines that are the same as `[!code skip]`. `skippedCode.commentAliases` (default `{ '*': ['...'] }`) reads a comment that holds only an alias (`// ...`, `# ...`). `skippedCode.bareAliases` (default `{ json: ['...'] }`) reads the alias alone on its line, with no comment. Both are by language: `*` applies to every language without its own entry, your keys merge over the defaults, and `[]` turns a language off. For a bare `...` in YAML, set `bareAliases: { yaml: ['...'] }`.
+- An alias changes only how the line looks. Line numbers, ranges and the copied code stay the same.
+- A comment with other text, such as `// ... and so on`, stays in the code. Use it to keep `// ...` as code in one block. For a marker with text, use `[!code skip] text`.
+- During the animation of a code walkthrough or scrollycoding step, a marker line shows empty.
+- `skippedCode: false` leaves `[!code skip]` in the code.
+
## Expandable blocks
Docs: https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/