From 149d5571138819f66f13a452c14a4bfee3c87463 Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 12:50:08 +0100 Subject: [PATCH 01/11] skipped-code: add `[!code skip]`, a marker for code that a block leaves out A dotted rule with a badge takes the place of the directive line, at its indentation. The badge reads "Code not shown", or the text after the directive. The marker is static HTML and stays out of the copied text. A directive on its own line at the end of a block puts the marker after the last line, through a new `endOfBlock` directive setting. `skippedCode: false` turns the feature off. Part of #28. Co-Authored-By: Claude Opus 5.5 --- .agents/DECISIONS.md | 1 + .github/assets/readme/skipped-code.png | Bin 0 -> 24168 bytes AGENTS.md | 2 +- README.md | 21 +++- docs/e2e/carousel.test.ts | 14 +-- docs/e2e/skipped-code.test.ts | 49 ++++++++ docs/src/components/FeatureCarousel.astro | 1 + .../content/docs/features/skipped-code.mdx | 116 ++++++++++++++++++ docs/src/content/docs/index.mdx | 20 ++- .../reference/expressive-code-plugins.mdx | 1 + docs/src/sidebar.mjs | 1 + packages/starlight-codeblocks/README.md | 21 +++- .../src/expressive-code/core.ts | 14 ++- .../src/expressive-code/index.ts | 4 + .../src/expressive-code/notation.ts | 8 +- .../src/expressive-code/skipped-code.ts | 113 +++++++++++++++++ .../starlight-codeblocks/src/languages/ca.ts | 1 + .../starlight-codeblocks/src/languages/de.ts | 1 + .../starlight-codeblocks/src/languages/eo.ts | 1 + .../starlight-codeblocks/src/languages/es.ts | 1 + .../starlight-codeblocks/src/languages/fr.ts | 1 + .../starlight-codeblocks/src/languages/hi.ts | 1 + .../starlight-codeblocks/src/languages/id.ts | 1 + .../starlight-codeblocks/src/languages/it.ts | 1 + .../starlight-codeblocks/src/languages/ja.ts | 1 + .../starlight-codeblocks/src/languages/ko.ts | 1 + .../starlight-codeblocks/src/languages/nb.ts | 1 + .../starlight-codeblocks/src/languages/pl.ts | 1 + .../starlight-codeblocks/src/languages/pt.ts | 1 + .../starlight-codeblocks/src/languages/ru.ts | 1 + .../starlight-codeblocks/src/languages/sv.ts | 1 + .../starlight-codeblocks/src/languages/tr.ts | 1 + .../starlight-codeblocks/src/languages/zh.ts | 1 + packages/starlight-codeblocks/src/options.ts | 9 +- .../starlight-codeblocks/src/reference.ts | 13 ++ .../starlight-codeblocks/src/translations.ts | 1 + .../starlight-codeblocks/test/compat.test.ts | 2 + .../test/decorations.test.ts | 1 + .../test/notation.test.ts | 8 ++ .../test/skipped-code.test.ts | 44 +++++++ .../starlight-codeblocks/test/styles.test.ts | 1 + scripts/readme-media.mjs | 1 + skills/starlight-codeblocks/SKILL.md | 7 +- .../references/configuration.md | 3 +- .../references/readability.md | 26 ++++ 45 files changed, 499 insertions(+), 20 deletions(-) create mode 100644 .github/assets/readme/skipped-code.png create mode 100644 docs/e2e/skipped-code.test.ts create mode 100644 docs/src/content/docs/features/skipped-code.mdx create mode 100644 packages/starlight-codeblocks/src/expressive-code/skipped-code.ts create mode 100644 packages/starlight-codeblocks/test/skipped-code.test.ts diff --git a/.agents/DECISIONS.md b/.agents/DECISIONS.md index f37c44c..cad7639 100644 --- a/.agents/DECISIONS.md +++ b/.agents/DECISIONS.md @@ -96,6 +96,7 @@ The choices that the code does not explain, with the options that were rejected. - **Expandable blocks collapse only in the client**, with `hidden="until-found"`, so a block is complete without JavaScript and find in page reveals lines. Collapsed lines use `content-visibility: hidden` because EC's `all: revert` removes the browser's until-found style. `auto` skips code tabs variants, runnable blocks and collapsible sections; the components remove an `auto` cap. - **The hidden-lines toggle label changes, with no `aria-pressed`**, which would contradict the label. Open hidden lines dim to 0.75 opacity by the user's choice; syntax colours stay at 3:1 or more, and the accessibility page lists it as an exception with `openOpacity: '1'` to turn it off. - **A manual selection leaves out closed hidden lines.** The copy button includes them. *Rejected:* a `copy` handler that adds them (the paste would differ from the selection). +- **Skipped code is a directive only, `[!code skip]`**, written where an author would write `// ...`. The marker is static HTML with no client module, and not a button, as there is nothing to open. It takes the indentation of the directive line, and a directive line at the end of the block puts it after the last line (`endOfBlock` on the directive spec). A dotted rule tells it apart from the dashed hidden lines marker. *Rejected:* a `skip={range}` attribute (a range names lines, not the gaps between them, and cannot name the end); `:N` as a count of skipped lines that makes line numbers jump (other directives read `:N` as the lines they apply to). ### Copy, run, playgrounds, placeholders diff --git a/.github/assets/readme/skipped-code.png b/.github/assets/readme/skipped-code.png new file mode 100644 index 0000000000000000000000000000000000000000..b2fa86752e92b5c7793da53cdb7fc9dc1391b7cc GIT binary patch literal 24168 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%0A=456OI;1BA~-bJ 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 V&FDzo8o19D)km6&74lDB{uitqGpqmr literal 0 HcmV?d00001 diff --git a/AGENTS.md b/AGENTS.md index 15536b4..5be260b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent instructions -`starlight-codeblocks` is a Starlight plugin that adds 28 code block features on top of Expressive Code (EC), which renders every code block in Starlight. `packages/starlight-codeblocks/` is the plugin, `docs/` its Starlight docs site (it uses the plugin through `workspace:*`, and defines each feature's syntax and behaviour), `examples/astro/` a minimal Astro site without Starlight, and `skills/starlight-codeblocks/` an agent skill for people who use the plugin. +`starlight-codeblocks` is a Starlight plugin that adds 29 code block features on top of Expressive Code (EC), which renders every code block in Starlight. `packages/starlight-codeblocks/` is the plugin, `docs/` its Starlight docs site (it uses the plugin through `workspace:*`, and defines each feature's syntax and behaviour), `examples/astro/` a minimal Astro site without Starlight, and `skills/starlight-codeblocks/` an agent skill for people who use the plugin. - `.agents/DECISIONS.md`: design decisions and the rejected options. Search it before you change existing behaviour. - `.agents/WRITING-STYLE.md`: how the docs read, the feature page template and the glossary. diff --git a/README.md b/README.md index 5ce0b10..ebccf20 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ starlight-codeblocks -A Starlight and Astro plugin that adds 28 features to code blocks, such as focus, line states, annotations, links to API docs and runnable examples. It builds on Expressive Code, so the code blocks you already have keep working. +A Starlight and Astro plugin that adds 29 features to code blocks, such as focus, line states, annotations, links to API docs and runnable examples. It builds on Expressive Code, so the code blocks you already have keep working. Using an agent? [Point it at the bundled skill](https://ewels.github.io/starlight-codeblocks/agent-skill/). @@ -244,6 +244,25 @@ Hide the imports and set-up that readers need to run an example but not to under +
+Skipped code + +Show a marker where a code block leaves out code, so readers know the file has more lines there. The copied code has no marker. + +````md +```js +app.get('/users', async (req, res) => { + // [!code skip] Read the users from the database +}); +``` +```` + +A JavaScript block with a dotted line and the text Read the users from the database in place of a function body. + +[Skipped code documentation](https://ewels.github.io/starlight-codeblocks/features/skipped-code/) + +
+
Expandable blocks diff --git a/docs/e2e/carousel.test.ts b/docs/e2e/carousel.test.ts index dcc253c..ecb8e00 100644 --- a/docs/e2e/carousel.test.ts +++ b/docs/e2e/carousel.test.ts @@ -149,7 +149,7 @@ test('a button or a dot shows its example, announces it and marks itself, and th await expect(page.locator('.carousel .slide:not([data-current])').first()).toBeHidden(); await expect(page.locator('.carousel .tile[aria-pressed="true"]')).toHaveCount(1); await expect(tile(page, 'Word-level diff')).toHaveAttribute('aria-pressed', 'true'); - await expect(page.locator('.carousel [data-status]')).toHaveText('Word-level diff, 18 of 27'); + await expect(page.locator('.carousel [data-status]')).toHaveText('Word-level diff, 19 of 28'); // The current button differs by more than colour. expect(await css(tile(page, 'Word-level diff'), 'fontWeight')).toBe('600'); expect(await css(tile(page, 'Footnotes'), 'fontWeight')).toBe('400'); @@ -159,7 +159,7 @@ test('a button or a dot shows its example, announces it and marks itself, and th await expect(dot(page, 'Focus')).toHaveAttribute('aria-current', 'true'); await expect(dot(page, 'Word-level diff')).toHaveAttribute('aria-current', 'false'); await expect(tile(page, 'Focus')).toHaveAttribute('aria-pressed', 'true'); - await expect(page.locator('.carousel [data-status]')).toHaveText(/^Focus, \d+ of 27$/); + await expect(page.locator('.carousel [data-status]')).toHaveText(/^Focus, \d+ of 28$/); await expect(page.locator('.carousel .rotation')).toHaveAccessibleName('Play'); }); @@ -173,8 +173,8 @@ test('the buttons are a flat list in sidebar order, in columns, with one dot eac await page.goto('./'); await expect(page.locator('.carousel .group-label')).toHaveCount(0); const tiles = page.locator('.carousel .tile'); - await expect(tiles).toHaveCount(27); - await expect(page.locator('.carousel .tile svg[aria-hidden], .carousel .tile [aria-hidden] svg')).toHaveCount(27); + await expect(tiles).toHaveCount(28); + await expect(page.locator('.carousel .tile svg[aria-hidden], .carousel .tile [aria-hidden] svg')).toHaveCount(28); const tileIds = await tiles.evaluateAll((els) => els.map((el) => el.getAttribute('data-feature'))); expect(tileIds).toEqual(sidebarIds.filter((id) => tileIds.includes(id))); @@ -189,9 +189,9 @@ test('the buttons are a flat list in sidebar order, in columns, with one dot eac expect(boxes.every(([x], i) => i === 0 || x >= (boxes[i - 1]?.[0] ?? 0))).toBe(true); for (const column of columns) expect(column).toEqual((columns[0] ?? []).slice(0, column.length)); // The phone viewport (360px) is too narrow for the auto column width, so it's forced to two. - if (phone()) expect(lengths).toEqual([14, 13]); + if (phone()) expect(lengths).toEqual([14, 14]); - await expect(page.locator('.carousel .dot')).toHaveCount(27); + await expect(page.locator('.carousel .dot')).toHaveCount(28); const order = await page.locator('.carousel .controls > *').evaluateAll((els) => els.map((el) => el.className)); expect(order.at(-1)).toContain('rotation'); }); @@ -316,7 +316,7 @@ test.describe('without JavaScript', () => { 'href', '/starlight-codeblocks/features/focus/', ); - await expect(page.locator('.carousel a.tile')).toHaveCount(27); + await expect(page.locator('.carousel a.tile')).toHaveCount(28); const docsLink = page.getByRole('link', { name: 'Read docs : Annotations' }); await expect(docsLink).toBeVisible(); await expect(docsLink).toHaveAttribute('href', '/starlight-codeblocks/features/annotations/'); diff --git a/docs/e2e/skipped-code.test.ts b/docs/e2e/skipped-code.test.ts new file mode 100644 index 0000000..b3539ed --- /dev/null +++ b/docs/e2e/skipped-code.test.ts @@ -0,0 +1,49 @@ +import { expect, test } from '@playwright/test'; +import { example } from './helpers.ts'; + +test.beforeEach(async ({ page }) => { + await page.goto('./features/skipped-code/'); +}); + +test('a marker starts at the indentation of its directive line, and every marker has the same height', async ({ + page, +}) => { + const markers = example(page).locator('.scb-skip-marker'); + await expect(markers).toHaveCount(2); + const result = await example(page) + .locator('pre code') + .evaluate((code) => { + const left = (el: Element) => el.getBoundingClientRect().left; + const range = document.createRange(); + range.selectNodeContents(code.querySelector('.ec-line .code span') as Node); + const probe = document.createElement('span'); + probe.textContent = 'xx'; + code.append(probe); + const ch = probe.getBoundingClientRect().width / 2; + probe.remove(); + const [indented, plain] = [...code.querySelectorAll('.scb-skip-marker')]; + const text = (marker?: Element) => left(marker?.querySelector('.scb-skip-text') as Element); + return { + lineStart: range.getBoundingClientRect().left, + indented: text(indented), + plain: text(plain), + ch, + heights: [indented, plain].map((m) => m?.getBoundingClientRect().height), + }; + }); + expect(Math.abs(result.plain - result.lineStart)).toBeLessThan(1); + expect(Math.abs(result.indented - result.plain - 2 * result.ch)).toBeLessThan(1); + expect(Math.abs((result.heights[0] ?? 0) - (result.heights[1] ?? 0))).toBeLessThan(1); +}); + +test('a manual selection leaves out the marker text', async ({ page }) => { + const text = await example(page) + .locator('pre code') + .evaluate((code) => { + getSelection()?.selectAllChildren(code); + return getSelection()?.toString(); + }); + expect(text).not.toContain('Read the users'); + expect(text).not.toContain('Code not shown'); + expect(text).toContain('res.status(201).json(user);'); +}); diff --git a/docs/src/components/FeatureCarousel.astro b/docs/src/components/FeatureCarousel.astro index c8ffa35..1066c1c 100644 --- a/docs/src/components/FeatureCarousel.astro +++ b/docs/src/components/FeatureCarousel.astro @@ -18,6 +18,7 @@ const icons: Record = { 'features/split-diff': lucide.GitCompare, 'features/code-walkthrough': lucide.Replace, 'features/hidden-lines': lucide.EyeOff, + 'features/skipped-code': lucide.Ellipsis, 'features/expandable-blocks': lucide.ChevronsUpDown, 'features/visible-whitespace': lucide.Pilcrow, 'features/colourised-brackets': lucide.Braces, diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx new file mode 100644 index 0000000..d821c57 --- /dev/null +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -0,0 +1,116 @@ +--- +title: Skipped code +description: Show a marker where a code block leaves out code, so readers know the file has more lines there. +--- + +import { LinkCard } from '@astrojs/starlight/components'; +import Example from '../../../components/Example.astro'; + +An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. The `[!code skip]` directive puts a marker in its place, which looks different from the code and is not part of the copied text. + +export const basic = ` +\`\`\`js title="routes.js" +const app = express(); + +app.get('/users', async (req, res) => { + // [!code skip] Read the users from the database +}); + +app.post('/users', async (req, res) => { + const user = await db.users.create(req.body); + res.status(201).json(user); +}); +// [!code skip] +\`\`\` +`; + + + +The first marker replaces the body of the `get` handler and shows the text after the directive. The second marker shows that the file goes on after the last line. Copying the block gives the code without the markers. + +## Syntax + +| Syntax | Where | +|---|---| +| `[!code skip]` | Comment on its own line, or at the end of a line | +| `[!code skip] text` | Comment on its own line, or at the end of a line | + +Put the directive on its own line where the code is left out. The marker takes the place of that line, with the same indentation. At the end of a line, the marker goes above that line. Without text, the marker reads "Code not shown". The text can hold inline code, links and bold text. + +## Examples + +### Skip the start of a file + +A marker on the first line shows that the example starts in the middle of a file: + +export const start = ` +\`\`\`py title="report.py" +# [!code skip] Imports and settings +def summarise(rows): + totals = {} + for row in rows: + totals[row["status"]] = totals.get(row["status"], 0) + 1 + return totals +\`\`\` +`; + + + +### Skip a section of a configuration file + +YAML uses `#` comments. For JSON, use `jsonc`, because JSON has no comments: + +export const config = ` +\`\`\`yaml title="docker-compose.yml" +services: + web: + image: nginx:1.27 + ports: + - "8080:80" + # [!code skip] The database and cache services +volumes: + data: +\`\`\` +`; + + + +## Behaviour + +- The marker: + - A dotted rule across the block, with the text in a badge at the indentation of the directive line. + - The marker is not a button. Readers cannot open it, because the code is not in the block. +- Line numbers: + - The marker has no line number, and the line numbers do not jump over it. +- Copy and selection: + - The copy button copies the code without the markers. A manual selection never includes the text of a marker. +- Screen readers: + - Screen readers read the text of the marker in its place among the lines. +- Print: + - Markers print. + +## Options + +Skipped code has no options. Turn the feature off for the whole site with `skippedCode: false`: + +```js title="astro.config.mjs" +codeblocks({ + skippedCode: false, +}); +``` + +With `skippedCode: false`, the plugin does not know the `[!code skip]` directive. It leaves the directive in the code as written, and logs a build warning. + + + +## Limitations + +- The directive needs a comment. A language without comments, such as JSON, cannot use it. Use `jsonc` for JSON. +- Line numbers do not jump over the skipped code. To start a block at a later number, use the `startLineNumber` attribute of Expressive Code. +- The copied code is incomplete, so it can fail to run. Do not use skipped code in a block with a **Run code** or playground button. + +## Related + +- [Hidden lines](/starlight-codeblocks/features/hidden-lines/): keep the lines in the block and the copied code, behind a marker that readers can open. +- [Expandable blocks](/starlight-codeblocks/features/expandable-blocks/): show a full file, cut to its first lines until the reader asks for the rest. +- [Comment notation](/starlight-codeblocks/comment-notation/): the directive syntax that `[!code skip]` uses. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 1a7590f..3ca561f 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -4,7 +4,7 @@ description: A plugin for Starlight and Astro that adds focus, line states, anno template: splash hero: tagline: | - This plugin adds 28 features to the Expressive Code blocks of + This plugin adds 29 features to the Expressive Code blocks of Starlight and Astro sites. Use them to enrich code blocks. Using an agent? Point it at the bundled skill. @@ -231,6 +231,24 @@ for key, value in config.items(): + + +```js title="routes.js" +const app = express(); + +app.get('/users', async (req, res) => { + // [!code skip] Read the users from the database +}); + +app.post('/users', async (req, res) => { + const user = await db.users.create(req.body); + res.status(201).json(user); +}); +// [!code skip] +``` + + + ```py title="report.py" expandable={8} apiLinks=false diff --git a/docs/src/content/docs/reference/expressive-code-plugins.mdx b/docs/src/content/docs/reference/expressive-code-plugins.mdx index 3e26b68..314bdf6 100644 --- a/docs/src/content/docs/reference/expressive-code-plugins.mdx +++ b/docs/src/content/docs/reference/expressive-code-plugins.mdx @@ -67,6 +67,7 @@ Each plugin takes the settings of its option, as the [options reference](/starli | `pluginPlaceholders(settings)` | `placeholders` | [Fill-in placeholders](/starlight-codeblocks/features/fill-in-placeholders/) | | `pluginMentions()` | `mentions` | [Code mentions](/starlight-codeblocks/features/code-mentions/) | | `pluginPermalinks()` | `permalinks` | [Line permalinks](/starlight-codeblocks/features/line-permalinks/) | +| `pluginSkippedCode()` | `skippedCode` | [Skipped code](/starlight-codeblocks/features/skipped-code/) | | `pluginHiddenLines()` | `hiddenLines` | [Hidden lines](/starlight-codeblocks/features/hidden-lines/) | | `pluginExpandable(settings)` | `expandable` | [Expandable blocks](/starlight-codeblocks/features/expandable-blocks/) | | `pluginPlayground(playgrounds)` | `playgrounds` | [Open in playground](/starlight-codeblocks/features/open-in-playground/) | diff --git a/docs/src/sidebar.mjs b/docs/src/sidebar.mjs index 1bbd3ec..c537bb0 100644 --- a/docs/src/sidebar.mjs +++ b/docs/src/sidebar.mjs @@ -29,6 +29,7 @@ export const sidebar = [ label: 'Make code easier to read', items: [ 'features/hidden-lines', + 'features/skipped-code', 'features/expandable-blocks', 'features/visible-whitespace', 'features/colourised-brackets', diff --git a/packages/starlight-codeblocks/README.md b/packages/starlight-codeblocks/README.md index 5ce0b10..ebccf20 100644 --- a/packages/starlight-codeblocks/README.md +++ b/packages/starlight-codeblocks/README.md @@ -2,7 +2,7 @@ starlight-codeblocks -A Starlight and Astro plugin that adds 28 features to code blocks, such as focus, line states, annotations, links to API docs and runnable examples. It builds on Expressive Code, so the code blocks you already have keep working. +A Starlight and Astro plugin that adds 29 features to code blocks, such as focus, line states, annotations, links to API docs and runnable examples. It builds on Expressive Code, so the code blocks you already have keep working. Using an agent? [Point it at the bundled skill](https://ewels.github.io/starlight-codeblocks/agent-skill/). @@ -244,6 +244,25 @@ Hide the imports and set-up that readers need to run an example but not to under
+
+Skipped code + +Show a marker where a code block leaves out code, so readers know the file has more lines there. The copied code has no marker. + +````md +```js +app.get('/users', async (req, res) => { + // [!code skip] Read the users from the database +}); +``` +```` + +A JavaScript block with a dotted line and the text Read the users from the database in place of a function body. + +[Skipped code documentation](https://ewels.github.io/starlight-codeblocks/features/skipped-code/) + +
+
Expandable blocks diff --git a/packages/starlight-codeblocks/src/expressive-code/core.ts b/packages/starlight-codeblocks/src/expressive-code/core.ts index 69d5db6..9c6cda9 100644 --- a/packages/starlight-codeblocks/src/expressive-code/core.ts +++ b/packages/starlight-codeblocks/src/expressive-code/core.ts @@ -79,6 +79,7 @@ const decorations = [ 'squiggle-popover', 'squiggle-list', 'hidden-marker', + 'skip-marker', 'expandable-bar', 'steps-stepper', 'steps-controls', @@ -111,18 +112,25 @@ const lineElements = new WeakMap(); */ export const lineElement = (line: ExpressiveCodeLine) => lineElements.get(line); -/** Inserts `nodes` before `target`, wherever it is in `root`. */ -export function insertBefore(root: Parents, target: Element, ...nodes: ElementContent[]) { +function insertAt(offset: number, root: Parents, target: Element, nodes: ElementContent[]) { visit( root, (node) => node === target, (_, index, parent) => { - if (parent && index !== undefined) parent.children.splice(index, 0, ...nodes); + if (parent && index !== undefined) parent.children.splice(index + offset, 0, ...nodes); return EXIT; }, ); } +/** Inserts `nodes` before `target`, wherever it is in `root`. */ +export const insertBefore = (root: Parents, target: Element, ...nodes: ElementContent[]) => + insertAt(0, root, target, nodes); + +/** Inserts `nodes` after `target`, wherever it is in `root`. */ +export const insertAfter = (root: Parents, target: Element, ...nodes: ElementContent[]) => + insertAt(1, root, target, nodes); + type Context = Pick; export const lineData = new AttachedPluginData<{ lines?: readonly ExpressiveCodeLine[] }>(() => ({})); diff --git a/packages/starlight-codeblocks/src/expressive-code/index.ts b/packages/starlight-codeblocks/src/expressive-code/index.ts index 369c268..f7e248d 100644 --- a/packages/starlight-codeblocks/src/expressive-code/index.ts +++ b/packages/starlight-codeblocks/src/expressive-code/index.ts @@ -21,6 +21,7 @@ import { pluginPlaceholders } from './placeholders.ts'; import { pluginPlayground } from './playground.ts'; import { pluginRunnable } from './runnable.ts'; import { pluginShellCopy } from './shell-copy.ts'; +import { pluginSkippedCode } from './skipped-code.ts'; import { pluginSplitDiff } from './split-diff.ts'; import { pluginSquiggles } from './squiggles.ts'; import { pluginSwatches } from './swatches.ts'; @@ -51,6 +52,7 @@ export { pluginPlayground, pluginRunnable, pluginShellCopy, + pluginSkippedCode, pluginSplitDiff, pluginSquiggles, pluginSwatches, @@ -92,6 +94,8 @@ export function createPlugins(options: ResolvedOptions, base?: string): Expressi ...(options.placeholders ? [pluginPlaceholders(options.placeholders)] : []), ...(options.mentions ? [pluginMentions()] : []), ...(options.permalinks ? [pluginPermalinks()] : []), + // Before hidden lines, so that its marker sits above a hidden lines marker on the same line. + ...(options.skippedCode ? [pluginSkippedCode()] : []), ...(options.hiddenLines ? [pluginHiddenLines()] : []), ...(options.expandable ? [pluginExpandable(options.expandable)] : []), // After shell copy, which changes the copied text that the playground gets, and after placeholders. diff --git a/packages/starlight-codeblocks/src/expressive-code/notation.ts b/packages/starlight-codeblocks/src/expressive-code/notation.ts index 13b21e4..2b2675f 100644 --- a/packages/starlight-codeblocks/src/expressive-code/notation.ts +++ b/packages/starlight-codeblocks/src/expressive-code/notation.ts @@ -5,6 +5,8 @@ import { type CodeblocksPlugin, lineData, lineElement, numberedLines, resolveRan export interface DirectiveSpec { /** The directive takes the text after it, up to the next directive or the end of the comment. */ text?: boolean; + /** On a line of its own at the end of the block, the directive applies after the last line, with `after`. */ + endOfBlock?: boolean; /** For the directives reference page. */ docs?: { description: string; @@ -29,6 +31,8 @@ export interface Directive { text?: string; /** The line of the directive in the code block source, from 1. */ sourceLine: number; + /** The directive comes after its line: see `DirectiveSpec.endOfBlock`. */ + after?: boolean; } const wordChar = /[\w$]/; @@ -316,8 +320,10 @@ export function parseNotation( return false; }); } + const last = parsed.findLast((line) => !line.removed); for (const directive of pending) { - report(`\`[!${directive.name}]\` has no line below it.`, directive.sourceLine); + if (last && specs[directive.name]?.endOfBlock) last.directives.push({ ...directive, after: true }); + else report(`\`[!${directive.name}]\` has no line below it.`, directive.sourceLine); } return parsed; } diff --git a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts new file mode 100644 index 0000000..3ea0386 --- /dev/null +++ b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts @@ -0,0 +1,113 @@ +import { + AttachedPluginData, + onBackground, + PluginStyleSettings, + setAlpha, + type UnresolvedStyleValue, +} from '@expressive-code/core'; +import { h, select } from '@expressive-code/core/hast'; +import { uiTexts } from '../translations.ts'; +import { type CodeblocksPlugin, insertAfter, insertBefore, lineElement } from './core.ts'; +import { inlineMarkdown } from './inline-markdown.ts'; +import { getDirectives, getRenderedDirectives } from './notation.ts'; +import { PREFIX, solidCodeBackground } from './styles.ts'; + +export interface SkippedCodeStyleSettings { + badgeBackground: UnresolvedStyleValue; + rule: UnresolvedStyleValue; +} + +declare module '@expressive-code/core' { + export interface StyleSettings { + codeblocksSkippedCode: SkippedCodeStyleSettings; + } +} + +const styleSettings = new PluginStyleSettings({ + defaultValues: { + codeblocksSkippedCode: { + badgeBackground: (context) => + onBackground(setAlpha(context.resolveSetting('codeblocks.mutedForeground'), 0.1), solidCodeBackground(context)), + rule: ({ resolveSetting }) => setAlpha(resolveSetting('codeblocks.mutedForeground'), 0.35), + }, + }, +}); + +/** The indentation of each directive's source line, by source line. */ +const indentData = new AttachedPluginData>(() => new Map()); + +/** Shows a marker where `[!code skip]` stands for code that the block leaves out. */ +export function pluginSkippedCode(): CodeblocksPlugin { + return { + name: 'starlight-codeblocks:skipped-code', + directives: { + 'code skip': { + text: true, + endOfBlock: true, + docs: { + description: 'Shows a marker in place of code that the block leaves out.', + args: 'Optional. The text of the marker.', + example: { lang: 'js', code: 'function connect(host) {\n // [!code skip]\n return socket\n}' }, + page: 'features/skipped-code', + }, + }, + }, + styleSettings, + baseStyles: ({ cssVar }) => ` +.${PREFIX}-skip-marker { + display: flex; + align-items: center; + position: relative; + margin: 2px 0; + padding-inline-start: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}); + color: ${cssVar('codeblocks.mutedForeground')}; + user-select: none; + -webkit-user-select: none; +} +/* An element, because a flex container drops text that is only whitespace. */ +.${PREFIX}-skip-indent { white-space: pre; line-height: 0; } +.${PREFIX}-skip-marker::before { + content: ''; + position: absolute; + top: 50%; + inset-inline: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}) ${cssVar('codePaddingInline')}; + border-top: 1px dotted ${cssVar('codeblocksSkippedCode.rule')}; +} +.${PREFIX}-skip-text { + position: relative; + z-index: 1; + padding: 0.05em 0.65em; + border-radius: 999px; + background: ${cssVar('codeblocksSkippedCode.badgeBackground')}; + font-size: 0.8125em; + line-height: 1.6; +} +`, + hooks: { + // The notation plugin deletes the directive's own line in `preprocessCode`. + preprocessMetadata({ codeBlock }) { + const lines = codeBlock.getLines(); + const indents = indentData.getOrCreateFor(codeBlock); + for (const { sourceLine } of getDirectives(codeBlock, 'code skip')) { + indents.set(sourceLine, lines[sourceLine - 1]?.text.match(/^\s*/)?.[0] ?? ''); + } + }, + postprocessRenderedBlock(context) { + const code = select('pre > code', context.renderData.blockAst); + if (!code) return; + const say = uiTexts(context.locale); + const indents = indentData.getOrCreateFor(context.codeBlock); + for (const { lines, text, after, sourceLine } of getRenderedDirectives(context, 'code skip')) { + const line = lines[0] && lineElement(lines[0]); + if (!line) continue; + const indent = indents.get(sourceLine); + const marker = h('div', { class: `${PREFIX}-skip-marker` }, [ + ...(indent ? [h('span', { class: `${PREFIX}-skip-indent` }, indent)] : []), + h('span', { class: `${PREFIX}-skip-text` }, text ? inlineMarkdown(text) : say('skippedCode.marker')), + ]); + (after ? insertAfter : insertBefore)(code, line, marker); + } + }, + }, + }; +} diff --git a/packages/starlight-codeblocks/src/languages/ca.ts b/packages/starlight-codeblocks/src/languages/ca.ts index c07ccae..ba045b6 100644 --- a/packages/starlight-codeblocks/src/languages/ca.ts +++ b/packages/starlight-codeblocks/src/languages/ca.ts @@ -24,6 +24,7 @@ export default { 'hiddenLines.hide_one': 'Amagar {{count}} línia', 'hiddenLines.hide_many': 'Amagar {{count}} de línies', 'hiddenLines.hide_other': 'Amagar {{count}} línies', + 'skippedCode.marker': 'Codi no mostrat', 'expandable.showAll_one': 'Mostrar {{count}} línia', 'expandable.showAll_many': 'Mostrar {{count}} de línies', 'expandable.showAll_other': 'Mostrar les {{count}} línies', diff --git a/packages/starlight-codeblocks/src/languages/de.ts b/packages/starlight-codeblocks/src/languages/de.ts index c487f76..0dc09cf 100644 --- a/packages/starlight-codeblocks/src/languages/de.ts +++ b/packages/starlight-codeblocks/src/languages/de.ts @@ -21,6 +21,7 @@ export default { 'hiddenLines.show_other': '{{count}} verborgene Zeilen anzeigen', 'hiddenLines.hide_one': '{{count}} Zeile verbergen', 'hiddenLines.hide_other': '{{count}} Zeilen verbergen', + 'skippedCode.marker': 'Code ausgelassen', 'expandable.showAll_one': '{{count}} Zeile anzeigen', 'expandable.showAll_other': 'Alle {{count}} Zeilen anzeigen', 'expandable.showFewer': 'Weniger Zeilen anzeigen', diff --git a/packages/starlight-codeblocks/src/languages/eo.ts b/packages/starlight-codeblocks/src/languages/eo.ts index b1aa9c0..0f871e3 100644 --- a/packages/starlight-codeblocks/src/languages/eo.ts +++ b/packages/starlight-codeblocks/src/languages/eo.ts @@ -21,6 +21,7 @@ export default { 'hiddenLines.show_other': 'Montri {{count}} kaŝitajn liniojn', 'hiddenLines.hide_one': 'Kaŝi {{count}} linion', 'hiddenLines.hide_other': 'Kaŝi {{count}} liniojn', + 'skippedCode.marker': 'Kodo ne montrita', 'expandable.showAll_one': 'Montri {{count}} linion', 'expandable.showAll_other': 'Montri ĉiujn {{count}} liniojn', 'expandable.showFewer': 'Montri malpli da linioj', diff --git a/packages/starlight-codeblocks/src/languages/es.ts b/packages/starlight-codeblocks/src/languages/es.ts index 32b1b22..ac8a9fe 100644 --- a/packages/starlight-codeblocks/src/languages/es.ts +++ b/packages/starlight-codeblocks/src/languages/es.ts @@ -24,6 +24,7 @@ export default { 'hiddenLines.hide_one': 'Ocultar {{count}} línea', 'hiddenLines.hide_many': 'Ocultar {{count}} de líneas', 'hiddenLines.hide_other': 'Ocultar {{count}} líneas', + 'skippedCode.marker': 'Código omitido', 'expandable.showAll_one': 'Mostrar {{count}} línea', 'expandable.showAll_many': 'Mostrar {{count}} de líneas', 'expandable.showAll_other': 'Mostrar las {{count}} líneas', diff --git a/packages/starlight-codeblocks/src/languages/fr.ts b/packages/starlight-codeblocks/src/languages/fr.ts index 1d7e6ef..83626fa 100644 --- a/packages/starlight-codeblocks/src/languages/fr.ts +++ b/packages/starlight-codeblocks/src/languages/fr.ts @@ -24,6 +24,7 @@ export default { 'hiddenLines.hide_one': 'Masquer {{count}} ligne', 'hiddenLines.hide_many': 'Masquer {{count}} de lignes', 'hiddenLines.hide_other': 'Masquer {{count}} lignes', + 'skippedCode.marker': 'Code omis', 'expandable.showAll_one': 'Afficher {{count}} ligne', 'expandable.showAll_many': 'Afficher {{count}} de lignes', 'expandable.showAll_other': 'Afficher les {{count}} lignes', diff --git a/packages/starlight-codeblocks/src/languages/hi.ts b/packages/starlight-codeblocks/src/languages/hi.ts index 7cb5ba0..fedd4bd 100644 --- a/packages/starlight-codeblocks/src/languages/hi.ts +++ b/packages/starlight-codeblocks/src/languages/hi.ts @@ -21,6 +21,7 @@ export default { 'hiddenLines.show_other': '{{count}} छिपी हुई पंक्तियाँ दिखाएँ', 'hiddenLines.hide_one': '{{count}} पंक्ति छिपाएँ', 'hiddenLines.hide_other': '{{count}} पंक्तियाँ छिपाएँ', + 'skippedCode.marker': 'कोड नहीं दिखाया गया', 'expandable.showAll_one': '{{count}} पंक्ति दिखाएँ', 'expandable.showAll_other': 'सभी {{count}} पंक्तियाँ दिखाएँ', 'expandable.showFewer': 'कम पंक्तियाँ दिखाएँ', diff --git a/packages/starlight-codeblocks/src/languages/id.ts b/packages/starlight-codeblocks/src/languages/id.ts index 3c8ae4b..e2b5ec0 100644 --- a/packages/starlight-codeblocks/src/languages/id.ts +++ b/packages/starlight-codeblocks/src/languages/id.ts @@ -18,6 +18,7 @@ export default { 'hiddenLines.marker_other': '{{count}} baris tersembunyi', 'hiddenLines.show_other': 'Tampilkan {{count}} baris tersembunyi', 'hiddenLines.hide_other': 'Sembunyikan {{count}} baris', + 'skippedCode.marker': 'Kode tidak ditampilkan', 'expandable.showAll_other': 'Tampilkan semua {{count}} baris', 'expandable.showFewer': 'Tampilkan lebih sedikit baris', 'splitDiff.view': 'Tampilan diff', diff --git a/packages/starlight-codeblocks/src/languages/it.ts b/packages/starlight-codeblocks/src/languages/it.ts index d153643..fd0cf04 100644 --- a/packages/starlight-codeblocks/src/languages/it.ts +++ b/packages/starlight-codeblocks/src/languages/it.ts @@ -24,6 +24,7 @@ export default { 'hiddenLines.hide_one': 'Nascondi {{count}} riga', 'hiddenLines.hide_many': 'Nascondi {{count}} di righe', 'hiddenLines.hide_other': 'Nascondi {{count}} righe', + 'skippedCode.marker': 'Codice omesso', 'expandable.showAll_one': 'Mostra {{count}} riga', 'expandable.showAll_many': 'Mostra {{count}} di righe', 'expandable.showAll_other': 'Mostra tutte le {{count}} righe', diff --git a/packages/starlight-codeblocks/src/languages/ja.ts b/packages/starlight-codeblocks/src/languages/ja.ts index b965a6a..fd655a4 100644 --- a/packages/starlight-codeblocks/src/languages/ja.ts +++ b/packages/starlight-codeblocks/src/languages/ja.ts @@ -18,6 +18,7 @@ export default { 'hiddenLines.marker_other': '非表示の {{count}} 行', 'hiddenLines.show_other': '非表示の {{count}} 行を表示', 'hiddenLines.hide_other': '{{count}} 行を非表示', + 'skippedCode.marker': 'コードは省略', 'expandable.showAll_other': '全 {{count}} 行を表示', 'expandable.showFewer': '表示する行を減らす', 'splitDiff.view': '差分の表示', diff --git a/packages/starlight-codeblocks/src/languages/ko.ts b/packages/starlight-codeblocks/src/languages/ko.ts index 82a68c4..d83c1f7 100644 --- a/packages/starlight-codeblocks/src/languages/ko.ts +++ b/packages/starlight-codeblocks/src/languages/ko.ts @@ -18,6 +18,7 @@ export default { 'hiddenLines.marker_other': '숨겨진 줄 {{count}}개', 'hiddenLines.show_other': '숨겨진 줄 {{count}}개 표시', 'hiddenLines.hide_other': '{{count}}줄 숨기기', + 'skippedCode.marker': '코드 생략', 'expandable.showAll_other': '전체 {{count}}줄 표시', 'expandable.showFewer': '더 적은 줄 표시', 'splitDiff.view': '차이 보기', diff --git a/packages/starlight-codeblocks/src/languages/nb.ts b/packages/starlight-codeblocks/src/languages/nb.ts index a370127..a3f14cb 100644 --- a/packages/starlight-codeblocks/src/languages/nb.ts +++ b/packages/starlight-codeblocks/src/languages/nb.ts @@ -21,6 +21,7 @@ export default { 'hiddenLines.show_other': 'Vis {{count}} skjulte linjer', 'hiddenLines.hide_one': 'Skjul {{count}} linje', 'hiddenLines.hide_other': 'Skjul {{count}} linjer', + 'skippedCode.marker': 'Kode utelatt', 'expandable.showAll_one': 'Vis {{count}} linje', 'expandable.showAll_other': 'Vis alle {{count}} linjene', 'expandable.showFewer': 'Vis færre linjer', diff --git a/packages/starlight-codeblocks/src/languages/pl.ts b/packages/starlight-codeblocks/src/languages/pl.ts index b6dba0c..8020014 100644 --- a/packages/starlight-codeblocks/src/languages/pl.ts +++ b/packages/starlight-codeblocks/src/languages/pl.ts @@ -27,6 +27,7 @@ export default { 'hiddenLines.hide_few': 'Ukryj {{count}} wiersze', 'hiddenLines.hide_many': 'Ukryj {{count}} wierszy', 'hiddenLines.hide_other': 'Ukryj {{count}} wiersza', + 'skippedCode.marker': 'Pominięty kod', 'expandable.showAll_one': 'Pokaż {{count}} wiersz', 'expandable.showAll_few': 'Pokaż wszystkie {{count}} wiersze', 'expandable.showAll_many': 'Pokaż wszystkie {{count}} wierszy', diff --git a/packages/starlight-codeblocks/src/languages/pt.ts b/packages/starlight-codeblocks/src/languages/pt.ts index 212cd65..e572d0f 100644 --- a/packages/starlight-codeblocks/src/languages/pt.ts +++ b/packages/starlight-codeblocks/src/languages/pt.ts @@ -24,6 +24,7 @@ export default { 'hiddenLines.hide_one': 'Ocultar {{count}} linha', 'hiddenLines.hide_many': 'Ocultar {{count}} de linhas', 'hiddenLines.hide_other': 'Ocultar {{count}} linhas', + 'skippedCode.marker': 'Código omitido', 'expandable.showAll_one': 'Mostrar {{count}} linha', 'expandable.showAll_many': 'Mostrar {{count}} de linhas', 'expandable.showAll_other': 'Mostrar todas as {{count}} linhas', diff --git a/packages/starlight-codeblocks/src/languages/ru.ts b/packages/starlight-codeblocks/src/languages/ru.ts index 1452498..4b815cc 100644 --- a/packages/starlight-codeblocks/src/languages/ru.ts +++ b/packages/starlight-codeblocks/src/languages/ru.ts @@ -27,6 +27,7 @@ export default { 'hiddenLines.hide_few': 'Скрыть {{count}} строки', 'hiddenLines.hide_many': 'Скрыть {{count}} строк', 'hiddenLines.hide_other': 'Скрыть {{count}} строки', + 'skippedCode.marker': 'Код опущен', 'expandable.showAll_one': 'Показать все {{count}} строку', 'expandable.showAll_few': 'Показать все {{count}} строки', 'expandable.showAll_many': 'Показать все {{count}} строк', diff --git a/packages/starlight-codeblocks/src/languages/sv.ts b/packages/starlight-codeblocks/src/languages/sv.ts index 0664565..a4f28fa 100644 --- a/packages/starlight-codeblocks/src/languages/sv.ts +++ b/packages/starlight-codeblocks/src/languages/sv.ts @@ -21,6 +21,7 @@ export default { 'hiddenLines.show_other': 'Visa {{count}} dolda rader', 'hiddenLines.hide_one': 'Dölj {{count}} rad', 'hiddenLines.hide_other': 'Dölj {{count}} rader', + 'skippedCode.marker': 'Kod utelämnad', 'expandable.showAll_one': 'Visa {{count}} rad', 'expandable.showAll_other': 'Visa alla {{count}} rader', 'expandable.showFewer': 'Visa färre rader', diff --git a/packages/starlight-codeblocks/src/languages/tr.ts b/packages/starlight-codeblocks/src/languages/tr.ts index 12816b6..bcf7be3 100644 --- a/packages/starlight-codeblocks/src/languages/tr.ts +++ b/packages/starlight-codeblocks/src/languages/tr.ts @@ -21,6 +21,7 @@ export default { 'hiddenLines.show_other': '{{count}} gizli satırı göster', 'hiddenLines.hide_one': '{{count}} satırı gizle', 'hiddenLines.hide_other': '{{count}} satırı gizle', + 'skippedCode.marker': 'Kod gösterilmiyor', 'expandable.showAll_one': '{{count}} satırı göster', 'expandable.showAll_other': 'Tüm {{count}} satırı göster', 'expandable.showFewer': 'Daha az satır göster', diff --git a/packages/starlight-codeblocks/src/languages/zh.ts b/packages/starlight-codeblocks/src/languages/zh.ts index dda67f0..d8161d8 100644 --- a/packages/starlight-codeblocks/src/languages/zh.ts +++ b/packages/starlight-codeblocks/src/languages/zh.ts @@ -18,6 +18,7 @@ export default { 'hiddenLines.marker_other': '已隐藏 {{count}} 行', 'hiddenLines.show_other': '显示隐藏的 {{count}} 行', 'hiddenLines.hide_other': '隐藏 {{count}} 行', + 'skippedCode.marker': '代码已省略', 'expandable.showAll_other': '显示全部 {{count}} 行', 'expandable.showFewer': '显示较少的行', 'splitDiff.view': '差异视图', diff --git a/packages/starlight-codeblocks/src/options.ts b/packages/starlight-codeblocks/src/options.ts index 21504be..01b0433 100644 --- a/packages/starlight-codeblocks/src/options.ts +++ b/packages/starlight-codeblocks/src/options.ts @@ -89,6 +89,7 @@ export interface CodeblocksOptions { annotations?: false | { style?: 'filled' | 'outline' }; footnotes?: false | { sticky?: boolean; style?: 'filled' | 'outline' }; hiddenLines?: false; + skippedCode?: false; shellCopy?: false | { prompts?: string[] }; wordDiff?: false | { minSimilarity?: number }; splitDiff?: false | { view?: 'unified' | 'split'; switch?: boolean; sync?: boolean }; @@ -206,7 +207,7 @@ const isDelimiters = (value: unknown) => // Attributes and directives of other features, which a custom state name would clash with. const reservedStateNames = new Set( - 'title frame mark ins del collapse wrap lang focus hidden hide highlight whitespace brackets swatches expandable playground id placeholder annotations footnotes label prefix step runnable note warn'.split( + 'title frame mark ins del collapse wrap lang focus hidden hide skip highlight whitespace brackets swatches expandable playground id placeholder annotations footnotes label prefix step runnable note warn'.split( ' ', ), ); @@ -317,6 +318,12 @@ export const optionsReference: Record = { description: 'Hides lines that readers need to run the code but not to understand it.', page: 'features/hidden-lines', }, + skippedCode: { + directives: true, + description: 'Shows a marker in place of code that a block leaves out.', + page: 'features/skipped-code', + off: '`[!code skip]` then stays in the code as written.', + }, shellCopy: { description: 'Adds a Copy commands button to terminal blocks with prompts, which copies the commands only.', page: 'features/smart-shell-copy', diff --git a/packages/starlight-codeblocks/src/reference.ts b/packages/starlight-codeblocks/src/reference.ts index e42f4b7..8fbe714 100644 --- a/packages/starlight-codeblocks/src/reference.ts +++ b/packages/starlight-codeblocks/src/reference.ts @@ -775,6 +775,19 @@ export const styleSettingsReference: Record = { openOpacity: { description: 'The opacity of the code of a hidden line that shows.' }, }, }, + codeblocksSkippedCode: { + page: 'features/skipped-code', + settings: { + badgeBackground: { + description: 'The background of the text on a marker.', + derived: '`codeblocks.mutedForeground` at 10% opacity on the code background.', + }, + rule: { + description: 'The dotted rule of a marker.', + derived: '`codeblocks.mutedForeground` at 35% opacity.', + }, + }, + }, codeblocksRunnable: { page: 'features/run-code', settings: { diff --git a/packages/starlight-codeblocks/src/translations.ts b/packages/starlight-codeblocks/src/translations.ts index 662467b..6de00e7 100644 --- a/packages/starlight-codeblocks/src/translations.ts +++ b/packages/starlight-codeblocks/src/translations.ts @@ -32,6 +32,7 @@ export const uiStrings = { 'hiddenLines.show_other': 'Show {{count}} hidden lines', 'hiddenLines.hide_one': 'Hide {{count}} line', 'hiddenLines.hide_other': 'Hide {{count}} lines', + 'skippedCode.marker': 'Code not shown', 'expandable.showAll_one': 'Show all {{count}} line', 'expandable.showAll_other': 'Show all {{count}} lines', 'expandable.showFewer': 'Show fewer lines', diff --git a/packages/starlight-codeblocks/test/compat.test.ts b/packages/starlight-codeblocks/test/compat.test.ts index cdeba7e..e61b43c 100644 --- a/packages/starlight-codeblocks/test/compat.test.ts +++ b/packages/starlight-codeblocks/test/compat.test.ts @@ -99,6 +99,8 @@ test('colours keep their contrast when a theme sets the code background to a CSS } const badge = get('codeblocksHiddenLines.badgeBackground'); expect(getColorContrast(get('codeblocks.mutedForeground'), badge), `${name} hidden`).toBeGreaterThanOrEqual(4.5); + const skipBadge = get('codeblocksSkippedCode.badgeBackground'); + expect(getColorContrast(get('codeblocks.mutedForeground'), skipBadge), `${name} skip`).toBeGreaterThanOrEqual(4.5); expect(getColorContrast(get('codeblocksPermalinks.foreground'), bg), `${name} permalink`).toBeGreaterThanOrEqual( 4.5, ); diff --git a/packages/starlight-codeblocks/test/decorations.test.ts b/packages/starlight-codeblocks/test/decorations.test.ts index e3dcdb2..140fd80 100644 --- a/packages/starlight-codeblocks/test/decorations.test.ts +++ b/packages/starlight-codeblocks/test/decorations.test.ts @@ -11,6 +11,7 @@ const blocks = [ block('js title="a.js" hidden={1} id="x" playground="typescript" run', 'setup();', 'main();'), block('js annotations="side"', 'run(a); // [!annotate] Runs it.'), block('sh placeholder="TOKEN"', 'curl -H "Bearer TOKEN"'), + block('js', 'a();', '// [!code skip]', 'b();', '// [!code skip] **Rest**'), ]; /** The text of each element that matches `selector` without the marked decorations, as a tool that drops `.scb-deco` reads it. */ diff --git a/packages/starlight-codeblocks/test/notation.test.ts b/packages/starlight-codeblocks/test/notation.test.ts index b8a2cae..0d9f5c6 100644 --- a/packages/starlight-codeblocks/test/notation.test.ts +++ b/packages/starlight-codeblocks/test/notation.test.ts @@ -10,6 +10,7 @@ const specs: DirectiveSpecs = { mention: {}, callout: { text: true }, link: {}, + 'code skip': { text: true, endOfBlock: true }, }; const js = commentSyntaxFor('js'); @@ -157,6 +158,13 @@ describe('parseNotation', () => { [expect.stringContaining('has no line below it'), 2], ]); }); + + test('moves an endOfBlock directive at the end of the block to the last line, after it', () => { + const { parsed, problems } = parseBlock(['a()', 'b()', '// [!code skip] Rest', '// [!code focus]']); + expect(problems).toEqual([[expect.stringContaining('has no line below it'), 4]]); + expect(parsed[1]?.directives).toMatchObject([{ name: 'code skip', text: 'Rest', after: true }]); + expect(parseBlock(['// [!code skip]']).problems).toEqual([[expect.stringContaining('has no line below it'), 1]]); + }); }); test('commentSyntaxFor uses the built-in map, Shiki aliases and the options', () => { diff --git a/packages/starlight-codeblocks/test/skipped-code.test.ts b/packages/starlight-codeblocks/test/skipped-code.test.ts new file mode 100644 index 0000000..0023534 --- /dev/null +++ b/packages/starlight-codeblocks/test/skipped-code.test.ts @@ -0,0 +1,44 @@ +import { expect, test } from 'vitest'; +import { block, render } from './render.ts'; + +const marker = (html: string) => html.match(/
.*?<\/div>/g) ?? []; + +test('puts a marker where a [!code skip] line was, and leaves it out of the copied text', async () => { + const { html, copyText, warnings } = await render( + block('js', 'function connect() {', ' // [!code skip]', ' return socket;', '}'), + ); + expect(marker(html)).toEqual([ + '
Code not shown
', + ]); + expect(html.indexOf('scb-skip-marker')).toBeLessThan(html.indexOf('return')); + expect(html.indexOf('scb-skip-marker')).toBeGreaterThan(html.indexOf('connect')); + expect(copyText).toBe('function connect() {\n return socket;\n}'); + expect(warnings).toEqual([]); +}); + +test('takes the marker text from the directive, with inline Markdown', async () => { + const { html } = await render(block('py', 'import os', '# [!code skip] The `main()` function', 'main()')); + expect(marker(html)).toEqual([ + '
The main() function
', + ]); +}); + +test('puts a marker after the last line, from a [!code skip] line at the end', async () => { + const { html, copyText, warnings } = await render(block('js', 'const a = 1;', '// [!code skip] More')); + expect(html).toMatch(/>1<.*
More<\/span><\/div><\/code>/); + expect(copyText).toBe('const a = 1;'); + expect(warnings).toEqual([]); +}); + +test('puts a marker above a line with a trailing [!code skip]', async () => { + const { html } = await render(block('js', 'a();', 'b(); // [!code skip]')); + expect(html).toMatch(/>a<.*scb-skip-marker.*>b { + 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); +}); 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..30e1c66 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]` | A marker takes the place of the code. 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. | @@ -175,7 +176,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..b6a02fb 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` | None | 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/readability.md b/skills/starlight-codeblocks/references/readability.md index fefe8c2..c6dd0e9 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,31 @@ 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. A marker takes the place of a `// ...` comment, 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, or at the end of the line below that place | +| `[!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] 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. +- A directive line at the end of the block puts the marker after the last line. +- The copied code has no marker, and no skipped code. Do not use it in a block with a playground or the **Run code** button. +- Line numbers do not jump over the marker. +- JSON has no comments. Use `jsonc`. +- Option: `skippedCode: false` leaves `[!code skip]` in the code. + ## Expandable blocks Docs: https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/ From e0156b60277004c9cd099808489b91830172587f Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 16:32:15 +0100 Subject: [PATCH 02/11] docs: add a skipped code example without marker text Co-Authored-By: Claude Opus 5.5 --- .../content/docs/features/skipped-code.mdx | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx index d821c57..ee7040c 100644 --- a/docs/src/content/docs/features/skipped-code.mdx +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -39,6 +39,27 @@ Put the directive on its own line where the code is left out. The marker takes t ## Examples +### Skip code without text + +Without text, the marker reads "Code not shown". Use it when the code around the marker tells readers what is left out: + +export const noText = ` +\`\`\`ts title="cache.ts" +export class Cache { + private entries = new Map(); + + // [!code skip] + + get(key: string): T | undefined { + return this.entries.get(key); + } + // [!code skip] +} +\`\`\` +`; + + + ### Skip the start of a file A marker on the first line shows that the example starts in the middle of a file: From 1504060c58662b73c164e0b76e1e8311fee4cb6f Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 17:50:26 +0100 Subject: [PATCH 03/11] skipped-code: read `// ...`, and `...` in languages with no comments, as `[!code skip]` A comment that holds only an alias, or the alias alone on its line in a language with no comment syntax such as JSON, gives the marker. `skippedCode.aliases` sets the aliases (default `['...']`). A bare `...` in Python or YAML stays code, and a language set to `[]` in `notation.comments` reads no aliases. `commentSyntaxFor` now returns `undefined` for a language with no comment syntax. Also adds the changelog entry for skipped code. Co-Authored-By: Claude Opus 5.5 --- .agents/DECISIONS.md | 2 +- docs/src/content/docs/comment-notation.mdx | 2 +- .../content/docs/features/skipped-code.mdx | 40 ++++++++++++-- packages/starlight-codeblocks/CHANGELOG.md | 1 + .../src/expressive-code/brackets.ts | 2 +- .../src/expressive-code/comments.ts | 10 ++-- .../src/expressive-code/index.ts | 2 +- .../src/expressive-code/notation.ts | 52 +++++++++++++++---- .../src/expressive-code/skipped-code.ts | 8 ++- packages/starlight-codeblocks/src/options.ts | 13 ++++- .../test/brackets.test.ts | 10 ++-- .../test/notation.test.ts | 27 +++++++--- .../starlight-codeblocks/test/options.test.ts | 2 + .../test/skipped-code.test.ts | 29 +++++++++++ skills/starlight-codeblocks/SKILL.md | 2 +- .../references/configuration.md | 2 +- .../references/readability.md | 7 ++- 17 files changed, 170 insertions(+), 41 deletions(-) diff --git a/.agents/DECISIONS.md b/.agents/DECISIONS.md index cad7639..96d1b76 100644 --- a/.agents/DECISIONS.md +++ b/.agents/DECISIONS.md @@ -96,7 +96,7 @@ The choices that the code does not explain, with the options that were rejected. - **Expandable blocks collapse only in the client**, with `hidden="until-found"`, so a block is complete without JavaScript and find in page reveals lines. Collapsed lines use `content-visibility: hidden` because EC's `all: revert` removes the browser's until-found style. `auto` skips code tabs variants, runnable blocks and collapsible sections; the components remove an `auto` cap. - **The hidden-lines toggle label changes, with no `aria-pressed`**, which would contradict the label. Open hidden lines dim to 0.75 opacity by the user's choice; syntax colours stay at 3:1 or more, and the accessibility page lists it as an exception with `openOpacity: '1'` to turn it off. - **A manual selection leaves out closed hidden lines.** The copy button includes them. *Rejected:* a `copy` handler that adds them (the paste would differ from the selection). -- **Skipped code is a directive only, `[!code skip]`**, written where an author would write `// ...`. The marker is static HTML with no client module, and not a button, as there is nothing to open. It takes the indentation of the directive line, and a directive line at the end of the block puts it after the last line (`endOfBlock` on the directive spec). A dotted rule tells it apart from the dashed hidden lines marker. *Rejected:* a `skip={range}` attribute (a range names lines, not the gaps between them, and cannot name the end); `:N` as a count of skipped lines that makes line numbers jump (other directives read `:N` as the lines they apply to). +- **Skipped code is the `[!code skip]` directive and its aliases**, written where an author would write `// ...`. The marker is static HTML with no client module, and not a button, as there is nothing to open. It takes the indentation of the directive line, and a directive line at the end of the block puts it after the last line (`endOfBlock` on the directive spec). A dotted rule tells it apart from the dashed hidden lines marker. A line that holds only an alias (`skippedCode.aliases`, default `...`) is the same directive: as a whole comment (`// ...`), or alone in a language with no comment syntax (JSON), so that `...` in Python or YAML stays code. Aliases take no text, so a comment such as `// ... more` stays as written. `[]` in `notation.comments` reads nothing, aliases too, so the docs' `md` source panes keep `...`. *Rejected:* a `skip={range}` attribute (a range names lines, not the gaps between them, and cannot name the end); `:N` as a count of skipped lines that makes line numbers jump (other directives read `:N` as the lines they apply to). ### Copy, run, playgrounds, placeholders diff --git a/docs/src/content/docs/comment-notation.mdx b/docs/src/content/docs/comment-notation.mdx index 4ae00a6..c2e55cb 100644 --- a/docs/src/content/docs/comment-notation.mdx +++ b/docs/src/content/docs/comment-notation.mdx @@ -283,7 +283,7 @@ codeblocks({ }); ``` -An entry replaces the built-in syntax of that language. A language name or its alias works: an entry for `powershell` also applies to ` ```pwsh `. The built-in map: +An entry replaces the built-in syntax of that language. A language name or its alias works: an entry for `powershell` also applies to ` ```pwsh `. An empty list, such as `md: []`, turns off directives for that language, including the `...` lines of [skipped code](/starlight-codeblocks/features/skipped-code/). The built-in map: diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx index ee7040c..b77709b 100644 --- a/docs/src/content/docs/features/skipped-code.mdx +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -5,8 +5,9 @@ description: Show a marker where a code block leaves out code, so readers know t import { LinkCard } from '@astrojs/starlight/components'; import Example from '../../../components/Example.astro'; +import Options from '../../../components/Options.astro'; -An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. The `[!code skip]` directive puts a marker in its place, which looks different from the code and is not part of the copied text. +An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. Skipped code puts a marker in its place, which looks different from the code and is not part of the copied text. Write the `[!code skip]` directive, with optional text, or keep the `// ...` comment. export const basic = ` \`\`\`js title="routes.js" @@ -34,9 +35,13 @@ The first marker replaces the body of the `get` handler and shows the text after |---|---| | `[!code skip]` | Comment on its own line, or at the end of a line | | `[!code skip] text` | Comment on its own line, or at the end of a line | +| `...` | Comment that holds only `...`, on its own line | +| `...` | On its own line, in a language with no comments, such as JSON | Put the directive on its own line where the code is left out. The marker takes the place of that line, with the same indentation. At the end of a line, the marker goes above that line. Without text, the marker reads "Code not shown". The text can hold inline code, links and bold text. +A comment that holds only `...`, such as `// ...` or `# ...`, is the same as `[!code skip]`. For a marker with text, use `[!code skip] text`. A comment with other text, such as `// ... more`, stays in the code. + ## Examples ### Skip code without text @@ -60,6 +65,27 @@ export class Cache { +### Skip code in JSON + +JSON has no comments. On its own line, `...` is the marker: + +export const json = ` +\`\`\`json title="package.json" +{ + "name": "my-site", + "scripts": { + "dev": "astro dev", + ... + }, + ... +} +\`\`\` +`; + + + +`...` alone on its line is a marker only in languages with no comments. In Python, `...` is code, and in YAML it ends a document, so these blocks keep it. + ### Skip the start of a file A marker on the first line shows that the example starts in the middle of a file: @@ -112,21 +138,25 @@ volumes: ## Options -Skipped code has no options. Turn the feature off for the whole site with `skippedCode: false`: + + +To add an alias, such as `…`, or to change `...`, set `aliases`: ```js title="astro.config.mjs" codeblocks({ - skippedCode: false, + skippedCode: { aliases: ['...', '…'] }, }); ``` -With `skippedCode: false`, the plugin does not know the `[!code skip]` directive. It leaves the directive in the code as written, and logs a build warning. +A language with `[]` in `notation.comments` reads no directives, so `...` stays in its blocks too. + +Turn the feature off for the whole site with `skippedCode: false`. The plugin then does not know the `[!code skip]` directive. It leaves the directive in the code as written, and logs a build warning. `...` lines also stay as written. ## Limitations -- The directive needs a comment. A language without comments, such as JSON, cannot use it. Use `jsonc` for JSON. +- The directive needs a comment. A language with no comments, such as JSON, can use only `...`, so its markers have no text. - Line numbers do not jump over the skipped code. To start a block at a later number, use the `startLineNumber` attribute of Expressive Code. - The copied code is incomplete, so it can fail to run. Do not use skipped code in a block with a **Run code** or playground button. diff --git a/packages/starlight-codeblocks/CHANGELOG.md b/packages/starlight-codeblocks/CHANGELOG.md index c378b80..0f29630 100644 --- a/packages/starlight-codeblocks/CHANGELOG.md +++ b/packages/starlight-codeblocks/CHANGELOG.md @@ -7,6 +7,7 @@ - Markdown plugins: `starlight-codeblocks/markdown` exports a Markdown plugin for each feature that changes Markdown, such as `mdastCodeTabs()`, and `mdastCodeblocks()` for all of them. `codeblocks()` adds only the ones that the Markdown processor does not already list, in the correct order among them. A listed plugin for a feature that is off stops the build (#36) - Split diff: a **Unified** and **Split** switch in 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 GitHub pull request does. `splitDiff.view`, `splitDiff.switch` and `splitDiff.sync` set the start view, remove the switch and stop it syncing across the page (#37) - Untitled blocks with title bar controls use the tab bar colours of titled blocks (#37) +- Skipped code: `[!code skip]` shows a marker in place of code that a block leaves out, at the indentation of its line. The text after the directive goes in the marker, else it reads "Code not shown". A directive on its own line at the end of a block puts the marker after the last line. A comment that holds only `...`, such as `// ...`, is the same, and so is `...` alone on its line in a language with no comments, such as JSON. `skippedCode.aliases` changes these. The copied code leaves out the marker. `skippedCode: false` turns it off (#28) ## 1.4.1 diff --git a/packages/starlight-codeblocks/src/expressive-code/brackets.ts b/packages/starlight-codeblocks/src/expressive-code/brackets.ts index 669fe81..86c8876 100644 --- a/packages/starlight-codeblocks/src/expressive-code/brackets.ts +++ b/packages/starlight-codeblocks/src/expressive-code/brackets.ts @@ -213,7 +213,7 @@ export function pluginBrackets({ const lines = codeBlock.getLines(); const matches = findBrackets( lines.map((line) => line.text), - commentSyntaxFor(codeBlock.language, comments), + commentSyntaxFor(codeBlock.language, comments) ?? [], charLiteralLanguages.has(codeBlock.language), ); for (const { line, column, depth, pairId } of matches) { diff --git a/packages/starlight-codeblocks/src/expressive-code/comments.ts b/packages/starlight-codeblocks/src/expressive-code/comments.ts index 2edb822..c31ed8b 100644 --- a/packages/starlight-codeblocks/src/expressive-code/comments.ts +++ b/packages/starlight-codeblocks/src/expressive-code/comments.ts @@ -35,14 +35,18 @@ export interface CommentSyntax { close?: string; } -export function commentSyntaxFor(language: string, overrides: Record = {}): CommentSyntax[] { +/** `undefined` for a language with no comment syntax. `[]` for a language whose comments the site turned off. */ +export function commentSyntaxFor( + language: string, + overrides: Record = {}, +): CommentSyntax[] | undefined { const key = language.toLowerCase(); const info = bundledLanguage(key); const keys = [key, ...(info ? [info.id, ...(info.aliases ?? [])] : [])]; const own = (syntaxes: Record) => keys.map((k) => (Object.hasOwn(syntaxes, k) ? syntaxes[k] : undefined)).find(Boolean); - const syntax = own(overrides) ?? own(defaultCommentSyntax) ?? []; - return syntax.map((entry) => { + const syntax = own(overrides) ?? own(defaultCommentSyntax); + return syntax?.map((entry) => { const [open = '', close] = entry.trim().split(/\s+/); return { open, close }; }); diff --git a/packages/starlight-codeblocks/src/expressive-code/index.ts b/packages/starlight-codeblocks/src/expressive-code/index.ts index f7e248d..4dbf7bc 100644 --- a/packages/starlight-codeblocks/src/expressive-code/index.ts +++ b/packages/starlight-codeblocks/src/expressive-code/index.ts @@ -95,7 +95,7 @@ export function createPlugins(options: ResolvedOptions, base?: string): Expressi ...(options.mentions ? [pluginMentions()] : []), ...(options.permalinks ? [pluginPermalinks()] : []), // Before hidden lines, so that its marker sits above a hidden lines marker on the same line. - ...(options.skippedCode ? [pluginSkippedCode()] : []), + ...(options.skippedCode ? [pluginSkippedCode(options.skippedCode)] : []), ...(options.hiddenLines ? [pluginHiddenLines()] : []), ...(options.expandable ? [pluginExpandable(options.expandable)] : []), // After shell copy, which changes the copied text that the playground gets, and after placeholders. diff --git a/packages/starlight-codeblocks/src/expressive-code/notation.ts b/packages/starlight-codeblocks/src/expressive-code/notation.ts index 2b2675f..5bca320 100644 --- a/packages/starlight-codeblocks/src/expressive-code/notation.ts +++ b/packages/starlight-codeblocks/src/expressive-code/notation.ts @@ -7,6 +7,11 @@ export interface DirectiveSpec { text?: boolean; /** On a line of its own at the end of the block, the directive applies after the last line, with `after`. */ endOfBlock?: boolean; + /** + * A line that holds only one of these, in a comment, is read as the directive. + * In a language with no comment syntax, the alias alone on its line. + */ + aliases?: string[]; /** For the directives reference page. */ docs?: { description: string; @@ -293,15 +298,36 @@ export function parseLine( return { text: newText, removed: false, directives }; } -/** Parses every line, and moves the directives of removed lines to the line below them. */ +/** The name of the directive whose alias is all of `line`, or all of a comment that is all of `line`. */ +function aliasOf(line: string, syntaxes: CommentSyntax[] | undefined, aliases: [alias: string, name: string][]) { + const text = line.trim(); + const bodies = syntaxes + ? syntaxes + .filter(({ open, close }) => text.startsWith(open) && (!close || text.endsWith(close))) + .map(({ open, close }) => text.slice(open.length, close ? -close.length : undefined).trim()) + : [text]; + return aliases.find(([alias]) => bodies.includes(alias))?.[1]; +} + +/** + * Parses every line, and moves the directives of removed lines to the line below them. + * `syntaxes` is `undefined` for a language with no comment syntax: only aliases apply there. + */ export function parseNotation( lines: string[], - syntaxes: CommentSyntax[], + syntaxes: CommentSyntax[] | undefined, specs: DirectiveSpecs, report: Report, diff = false, ): ParsedLine[] { - const parsed = lines.map((text, i) => parseLine(text, syntaxes, specs, report, i + 1, diff)); + const aliases = Object.entries(specs).flatMap(([name, spec]) => + (spec.aliases ?? []).map((alias): [string, string] => [alias.trim(), name]), + ); + const parsed = lines.map((text, i): ParsedLine => { + const name = aliases.length > 0 ? aliasOf(text, syntaxes, aliases) : undefined; + if (name) return { text: '', removed: true, directives: [{ name, count: 1, args: [], sourceLine: i + 1 }] }; + return syntaxes ? parseLine(text, syntaxes, specs, report, i + 1, diff) : { text, removed: false, directives: [] }; + }); let pending: Directive[] = []; for (const line of parsed) { if (line.removed) { @@ -445,11 +471,14 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl preprocessLanguage(context) { const { codeBlock, config } = context; const syntaxes = commentSyntaxFor(codeBlock.language, comments); - if (syntaxes.length === 0 || !/\[\\?!/.test(codeBlock.code)) return; + if (syntaxes?.length === 0) return; const specs: DirectiveSpecs = Object.assign( {}, ...config.plugins.map((plugin) => (plugin as CodeblocksPlugin).directives ?? {}), ); + const aliases = Object.values(specs).flatMap((spec) => spec.aliases ?? []); + const hasDirectives = syntaxes !== undefined && /\[\\?!/.test(codeBlock.code); + if (!hasDirectives && !aliases.some((alias) => codeBlock.code.includes(alias.trim()))) return; const lines = codeBlock.getLines(); const parsed = parseNotation( lines.map((line) => line.text), @@ -527,14 +556,15 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl preprocessCode({ codeBlock }) { const syntaxes = commentSyntaxFor(codeBlock.language, comments); const { removed, specs, diffIndent } = notationData.getOrCreateFor(codeBlock); - if (syntaxes.length === 0 || !/\[\\?!/.test(codeBlock.code)) return; for (const [line, columns] of diffIndent) line.editText(0, columns, ''); - for (const line of codeBlock.getLines()) { - // Other plugins can edit lines after the first parse, so parse the current text again. - const { text, removed: gone } = parseLine(line.text, syntaxes, specs, () => {}); - // The first parse kept this line, and blanking it would leave an empty line behind. - if (gone && !removed.includes(line)) continue; - if (text !== line.text) line.editText(0, line.text.length, text); + if (syntaxes?.length && /\[\\?!/.test(codeBlock.code)) { + for (const line of codeBlock.getLines()) { + // Other plugins can edit lines after the first parse, so parse the current text again. + const { text, removed: gone } = parseLine(line.text, syntaxes, specs, () => {}); + // The first parse kept this line, and blanking it would leave an empty line behind. + if (gone && !removed.includes(line)) continue; + if (text !== line.text) line.editText(0, line.text.length, text); + } } for (const line of removed) { const index = codeBlock.getLines().indexOf(line); diff --git a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts index 3ea0386..0ceea72 100644 --- a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts +++ b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts @@ -36,14 +36,20 @@ const styleSettings = new PluginStyleSettings({ /** The indentation of each directive's source line, by source line. */ const indentData = new AttachedPluginData>(() => new Map()); +export interface SkippedCodeSettings { + /** Lines that stand for `[!code skip]`, alone or as the whole of a comment. */ + aliases?: string[]; +} + /** Shows a marker where `[!code skip]` stands for code that the block leaves out. */ -export function pluginSkippedCode(): CodeblocksPlugin { +export function pluginSkippedCode({ aliases = ['...'] }: SkippedCodeSettings = {}): CodeblocksPlugin { return { name: 'starlight-codeblocks:skipped-code', directives: { 'code skip': { text: true, endOfBlock: true, + aliases, docs: { description: 'Shows a marker in place of code that the block leaves out.', args: 'Optional. The text of the marker.', diff --git a/packages/starlight-codeblocks/src/options.ts b/packages/starlight-codeblocks/src/options.ts index 01b0433..7d5f872 100644 --- a/packages/starlight-codeblocks/src/options.ts +++ b/packages/starlight-codeblocks/src/options.ts @@ -89,7 +89,7 @@ export interface CodeblocksOptions { annotations?: false | { style?: 'filled' | 'outline' }; footnotes?: false | { sticky?: boolean; style?: 'filled' | 'outline' }; hiddenLines?: false; - skippedCode?: false; + skippedCode?: false | { aliases?: string[] }; shellCopy?: false | { prompts?: string[] }; wordDiff?: false | { minSimilarity?: number }; splitDiff?: false | { view?: 'unified' | 'split'; switch?: boolean; sync?: boolean }; @@ -322,7 +322,16 @@ export const optionsReference: Record = { directives: true, description: 'Shows a marker in place of code that a block leaves out.', page: 'features/skipped-code', - off: '`[!code skip]` then stays in the code as written.', + off: '`[!code skip]` and `...` lines then stay in the code as written.', + fields: { + aliases: { + type: 'string[]', + default: ['...'], + description: + 'Lines that stand for `[!code skip]`: a comment that holds only an alias, or the alias alone on its line in a language with no comments, such as JSON. `[]` turns them off.', + valid: (value) => isStringArray(value) && (value as string[]).every((alias) => alias.trim() !== ''), + }, + }, }, shellCopy: { description: 'Adds a Copy commands button to terminal blocks with prompts, which copies the commands only.', diff --git a/packages/starlight-codeblocks/test/brackets.test.ts b/packages/starlight-codeblocks/test/brackets.test.ts index f7bc6c8..5bbccf1 100644 --- a/packages/starlight-codeblocks/test/brackets.test.ts +++ b/packages/starlight-codeblocks/test/brackets.test.ts @@ -7,9 +7,9 @@ import { setRegistry } from '../src/registry.ts'; import { variants } from './contrast.ts'; import { block, render } from './render.ts'; -const js = commentSyntaxFor('js'); +const js = commentSyntaxFor('js') ?? []; const at = (lines: string[], lang: string) => - findBrackets(lines, commentSyntaxFor(lang)).map(({ line, column }) => [line, column]); + findBrackets(lines, commentSyntaxFor(lang) ?? []).map(({ line, column }) => [line, column]); test('findBrackets pairs brackets by nesting depth, and leaves out unmatched ones and ones in strings and comments', () => { const text = 'const a = (1 + [2, 3]);'; @@ -52,7 +52,9 @@ test('findBrackets counts brackets in template literal interpolations, also in a test('findBrackets reads quotes, comments and strings per language', () => { const rust = ['impl Foo {', " fn name<'a>(&'a self) -> &'static str {", " let c = '{';", ' }', '}']; - const closers = findBrackets(rust, commentSyntaxFor('rust'), true).filter((m) => rust[m.line]?.[m.column] === '}'); + const closers = findBrackets(rust, commentSyntaxFor('rust') ?? [], true).filter( + (m) => rust[m.line]?.[m.column] === '}', + ); expect(closers.map((m) => m.line)).toEqual([3, 4]); expect(findBrackets(["it's (fine)"], [])).toHaveLength(2); const python = ['result = run(', ' """', ' Steps: 1) load', " ''' [ '''", ' """,', ')']; @@ -63,7 +65,7 @@ test('findBrackets reads quotes, comments and strings per language', () => { [0, 9], [4, 0], ]); - const hash = findBrackets(['count() {', ` n=\${#items[@]} # (note)`, '}'], commentSyntaxFor('bash')); + const hash = findBrackets(['count() {', ` n=\${#items[@]} # (note)`, '}'], commentSyntaxFor('bash') ?? []); expect(hash).toHaveLength(8); expect(hash.at(-1)).toMatchObject({ line: 2, column: 0, depth: 0 }); }); diff --git a/packages/starlight-codeblocks/test/notation.test.ts b/packages/starlight-codeblocks/test/notation.test.ts index 0d9f5c6..8d6d827 100644 --- a/packages/starlight-codeblocks/test/notation.test.ts +++ b/packages/starlight-codeblocks/test/notation.test.ts @@ -10,9 +10,9 @@ const specs: DirectiveSpecs = { mention: {}, callout: { text: true }, link: {}, - 'code skip': { text: true, endOfBlock: true }, + 'code skip': { text: true, endOfBlock: true, aliases: ['...'] }, }; -const js = commentSyntaxFor('js'); +const js = commentSyntaxFor('js') ?? []; function parse(text: string, syntaxes = js) { const problems: string[] = []; @@ -45,7 +45,7 @@ describe('parseLine', () => { ['lisp', "(setq x 'foo) ; it's [!code focus]", "(setq x 'foo) ; it's"], ['md', "Don't ", "Don't "], ])('%s: reads and removes the directive in %j', (lang, input, text) => { - const result = parse(input, commentSyntaxFor(lang)); + const result = parse(input, commentSyntaxFor(lang) ?? []); expect(result).toMatchObject({ text, removed: false, problems: [] }); expect(result.directives).toHaveLength(1); }); @@ -86,8 +86,8 @@ describe('parseLine', () => { test('removes lines that hold only directives', () => { expect(parse(' // [!callout /a/] Note')).toMatchObject({ removed: true, text: '' }); - expect(parse(' /* [!code focus] */', commentSyntaxFor('css'))).toMatchObject({ text: '', removed: true }); - const jsx = parse(' {/* [!callout] Note */}', commentSyntaxFor('tsx')); + expect(parse(' /* [!code focus] */', commentSyntaxFor('css') ?? [])).toMatchObject({ text: '', removed: true }); + const jsx = parse(' {/* [!callout] Note */}', commentSyntaxFor('tsx') ?? []); expect(jsx).toMatchObject({ removed: true, directives: [{ text: 'Note' }] }); }); @@ -108,7 +108,7 @@ describe('parseLine', () => { directives: [{ name: 'callout', text: 'Why' }], problems: [], }); - expect(parse('# fixes #12 [!callout /x/] Why', commentSyntaxFor('py'))).toMatchObject({ + expect(parse('# fixes #12 [!callout /x/] Why', commentSyntaxFor('py') ?? [])).toMatchObject({ removed: false, text: '# fixes #12', }); @@ -165,12 +165,25 @@ describe('parseNotation', () => { expect(parsed[1]?.directives).toMatchObject([{ name: 'code skip', text: 'Rest', after: true }]); expect(parseBlock(['// [!code skip]']).problems).toEqual([[expect.stringContaining('has no line below it'), 1]]); }); + + test('reads a line that holds only an alias, in a comment or in a language with no comments', () => { + const skip = (lines: string[], lang = 'js', comments = {}) => + parseNotation(lines, commentSyntaxFor(lang, comments), specs, () => {}).map(({ removed, directives }) => + removed ? 'removed' : directives.map((d) => d.name).join(), + ); + expect(skip(['a()', ' // ...', 'b()'])).toEqual(['', 'removed', 'code skip']); + expect(skip(['a()', '/* ... */'])).toEqual(['code skip', 'removed']); + expect(skip(['{', ' ...', '}'], 'json')).toEqual(['', 'removed', 'code skip']); + expect(skip(['a() // ...', '// ... more', '...', '//...x', '[...a]'])).toEqual(['', '', '', '', '']); + expect(skip(['def f():', ' ...', '# ...'], 'py')).toEqual(['', 'code skip', 'removed']); + expect(skip(['...', 'a'], 'json', { json: [] })).toEqual(['', '']); + }); }); test('commentSyntaxFor uses the built-in map, Shiki aliases and the options', () => { expect(commentSyntaxFor('Python')).toEqual([{ open: '#', close: undefined }]); expect(commentSyntaxFor('css')).toEqual([{ open: '/*', close: '*/' }]); - expect(commentSyntaxFor('json')).toEqual([]); + expect(commentSyntaxFor('json')).toBeUndefined(); expect(commentSyntaxFor('pwsh')).toEqual(commentSyntaxFor('powershell')); expect(commentSyntaxFor('shellsession')).toEqual([{ open: '#', close: undefined }]); expect(commentSyntaxFor('pwsh', { powershell: ['//'] })).toEqual([{ open: '//', close: undefined }]); diff --git a/packages/starlight-codeblocks/test/options.test.ts b/packages/starlight-codeblocks/test/options.test.ts index ae2d01d..8e37c61 100644 --- a/packages/starlight-codeblocks/test/options.test.ts +++ b/packages/starlight-codeblocks/test/options.test.ts @@ -14,6 +14,7 @@ test('turns every feature on with defaults, in new objects on each call', () => expect(options.footnotes).toEqual({ sticky: false, style: 'outline' }); expect(options.shellCopy).toEqual({ prompts: ['$ ', '> '] }); expect(options.expandable).toEqual({ lines: 12, auto: false }); + expect(options.skippedCode).toEqual({ aliases: ['...'] }); expect(options.inlineHighlighting).toEqual({ defaultLanguage: false }); expect(options.playgrounds).toEqual({}); expect(options.walkthrough).toEqual({ start: 1 }); @@ -62,6 +63,7 @@ test('rejects options that are not valid, with an OptionsError that names the op [{ annotations: { style: 'solid' } }, '`annotations.style` must be'], [{ footnotes: { style: 'solid' } }, '`footnotes.style` must be'], [{ expandable: { lines: 0 } }, '`expandable.lines` must be number, got 0'], + [{ skippedCode: { aliases: [' '] } }, '`skippedCode.aliases` must be'], [{ wordDiff: { minSimilarity: 2 } }, '`wordDiff.minSimilarity`'], [{ lineStates: { states: { todo: { label: 'To do', colour: '#fff' } } } }, '`lineStates.states` must be'], [{ lineStates: { states: { focus: { label: 'F', colour } } } }, '`lineStates.states`'], diff --git a/packages/starlight-codeblocks/test/skipped-code.test.ts b/packages/starlight-codeblocks/test/skipped-code.test.ts index 0023534..e112b7a 100644 --- a/packages/starlight-codeblocks/test/skipped-code.test.ts +++ b/packages/starlight-codeblocks/test/skipped-code.test.ts @@ -35,6 +35,35 @@ test('puts a marker above a line with a trailing [!code skip]', async () => { expect(html).toMatch(/>a<.*scb-skip-marker.*>b { + 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(marker(json.html)).toHaveLength(1); + expect(json.copyText).toBe('{\n "a": 1,\n}'); + expect(json.warnings).toEqual([]); +}); + +test('leaves `...` that is code, or that has 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(marker((await render(md)).html)).toEqual([]); + } +}); + +test('takes custom aliases, and none with `aliases: []`', async () => { + const md = block('js', 'a();', '// …', '// [...]', 'b();'); + expect(marker((await render(md, { skippedCode: { aliases: ['…', '[...]'] } })).html)).toHaveLength(2); + const { html, copyText } = await render(block('js', 'a();', '// ...', 'b();'), { skippedCode: { aliases: [] } }); + expect(marker(html)).toEqual([]); + expect(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); diff --git a/skills/starlight-codeblocks/SKILL.md b/skills/starlight-codeblocks/SKILL.md index 30e1c66..6c51335 100644 --- a/skills/starlight-codeblocks/SKILL.md +++ b/skills/starlight-codeblocks/SKILL.md @@ -77,7 +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]` | A marker takes the place of the code. The copied code is incomplete. | +| Code that the example leaves out, where authors write `// ...` | Skipped code: `[!code skip]`, or keep `// ...` | A marker takes the place of the code. 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. | diff --git a/skills/starlight-codeblocks/references/configuration.md b/skills/starlight-codeblocks/references/configuration.md index b6a02fb..61fd05d 100644 --- a/skills/starlight-codeblocks/references/configuration.md +++ b/skills/starlight-codeblocks/references/configuration.md @@ -32,7 +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` | None | Skipped code | +| `skippedCode` | `aliases`: lines that are the same as `[!code skip]`, default `['...']` | 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/readability.md b/skills/starlight-codeblocks/references/readability.md index c6dd0e9..552f4fe 100644 --- a/skills/starlight-codeblocks/references/readability.md +++ b/skills/starlight-codeblocks/references/readability.md @@ -49,6 +49,8 @@ Use where an example shows part of a file and leaves code out. A marker takes th |---|---| | `[!code skip]` | Comment on its own line where the code is left out, or at the end of the line below that place | | `[!code skip] text` | The same, with `text` on the marker in place of "Code not shown" | +| `...` | Comment that holds only `...` (`// ...`, `# ...`), on its own line | +| `...` | On its own line, in a language with no comments, such as JSON | ```js app.get('/users', async (req, res) => { @@ -61,8 +63,9 @@ app.get('/users', async (req, res) => { - A directive line at the end of the block puts the marker after the last line. - The copied code has no marker, and no skipped code. Do not use it in a block with a playground or the **Run code** button. - Line numbers do not jump over the marker. -- JSON has no comments. Use `jsonc`. -- Option: `skippedCode: false` leaves `[!code skip]` in the code. +- A comment with other text, such as `// ... more`, stays in the code. For a marker with text, use `[!code skip] text`. +- `...` alone on its line is a marker only in languages with no comments. In Python and YAML, it stays as code. +- Option: `skippedCode.aliases` (default `['...']`) sets the lines that are the same as `[!code skip]`. `[]` turns them off. `skippedCode: false` leaves `[!code skip]` and `...` in the code. ## Expandable blocks From e0ca29b2f54bc3d6d2df5f141d6c1b86e1b31608 Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 17:53:59 +0100 Subject: [PATCH 04/11] docs: show `// ...` in the skipped code syntax table, and prefix marker texts with "Not shown: " The alias note goes in a tip aside. The README image is regenerated. Co-Authored-By: Claude Opus 5.5 --- .github/assets/readme/skipped-code.png | Bin 24168 -> 24437 bytes README.md | 4 ++-- .../content/docs/features/skipped-code.mdx | 10 ++++++---- docs/src/content/docs/index.mdx | 2 +- packages/starlight-codeblocks/README.md | 4 ++-- .../references/readability.md | 4 ++-- 6 files changed, 13 insertions(+), 11 deletions(-) diff --git a/.github/assets/readme/skipped-code.png b/.github/assets/readme/skipped-code.png index b2fa86752e92b5c7793da53cdb7fc9dc1391b7cc..bbb08dd29b284ae9be4dd1f7c14dc43ba58f4fb6 100644 GIT binary patch literal 24437 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%0A=456OI;1BA~-bJ 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 V&FDzo8o19D)km6&74lDB{uitqGpqmr diff --git a/README.md b/README.md index ebccf20..26cd8ac 100644 --- a/README.md +++ b/README.md @@ -252,12 +252,12 @@ Show a marker where a code block leaves out code, so readers know the file has m ````md ```js app.get('/users', async (req, res) => { - // [!code skip] Read the users from the database + // [!code skip] Not shown: Read the users from the database }); ``` ```` -A JavaScript block with a dotted line and the text Read the users from the database in place of a function body. +A JavaScript block with a dotted line and the text Not shown: Read the users from the database in place of a function body. [Skipped code documentation](https://ewels.github.io/starlight-codeblocks/features/skipped-code/) diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx index b77709b..83aa352 100644 --- a/docs/src/content/docs/features/skipped-code.mdx +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -14,7 +14,7 @@ export const basic = ` const app = express(); app.get('/users', async (req, res) => { - // [!code skip] Read the users from the database + // [!code skip] Not shown: Read the users from the database }); app.post('/users', async (req, res) => { @@ -35,12 +35,14 @@ The first marker replaces the body of the `get` handler and shows the text after |---|---| | `[!code skip]` | Comment on its own line, or at the end of a line | | `[!code skip] text` | Comment on its own line, or at the end of a line | -| `...` | Comment that holds only `...`, on its own line | +| `// ...` | Comment that holds only `...`, on its own line. Use the comment syntax of the language, such as `# ...` | | `...` | On its own line, in a language with no comments, such as JSON | Put the directive on its own line where the code is left out. The marker takes the place of that line, with the same indentation. At the end of a line, the marker goes above that line. Without text, the marker reads "Code not shown". The text can hold inline code, links and bold text. +:::tip A comment that holds only `...`, such as `// ...` or `# ...`, is the same as `[!code skip]`. For a marker with text, use `[!code skip] text`. A comment with other text, such as `// ... more`, stays in the code. +::: ## Examples @@ -92,7 +94,7 @@ A marker on the first line shows that the example starts in the middle of a file export const start = ` \`\`\`py title="report.py" -# [!code skip] Imports and settings +# [!code skip] Not shown: Imports and settings def summarise(rows): totals = {} for row in rows: @@ -114,7 +116,7 @@ services: image: nginx:1.27 ports: - "8080:80" - # [!code skip] The database and cache services + # [!code skip] Not shown: The database and cache services volumes: data: \`\`\` diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 3ca561f..f94c328 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -237,7 +237,7 @@ for key, value in config.items(): const app = express(); app.get('/users', async (req, res) => { - // [!code skip] Read the users from the database + // [!code skip] Not shown: Read the users from the database }); app.post('/users', async (req, res) => { diff --git a/packages/starlight-codeblocks/README.md b/packages/starlight-codeblocks/README.md index ebccf20..26cd8ac 100644 --- a/packages/starlight-codeblocks/README.md +++ b/packages/starlight-codeblocks/README.md @@ -252,12 +252,12 @@ Show a marker where a code block leaves out code, so readers know the file has m ````md ```js app.get('/users', async (req, res) => { - // [!code skip] Read the users from the database + // [!code skip] Not shown: Read the users from the database }); ``` ```` -A JavaScript block with a dotted line and the text Read the users from the database in place of a function body. +A JavaScript block with a dotted line and the text Not shown: Read the users from the database in place of a function body. [Skipped code documentation](https://ewels.github.io/starlight-codeblocks/features/skipped-code/) diff --git a/skills/starlight-codeblocks/references/readability.md b/skills/starlight-codeblocks/references/readability.md index 552f4fe..39a9563 100644 --- a/skills/starlight-codeblocks/references/readability.md +++ b/skills/starlight-codeblocks/references/readability.md @@ -49,12 +49,12 @@ Use where an example shows part of a file and leaves code out. A marker takes th |---|---| | `[!code skip]` | Comment on its own line where the code is left out, or at the end of the line below that place | | `[!code skip] text` | The same, with `text` on the marker in place of "Code not shown" | -| `...` | Comment that holds only `...` (`// ...`, `# ...`), on its own line | +| `// ...` | Comment that holds only `...`, on its own line, in the comment syntax of the language (`# ...`) | | `...` | On its own line, in a language with no comments, such as JSON | ```js app.get('/users', async (req, res) => { - // [!code skip] Read the users from the database + // [!code skip] Not shown: Read the users from the database }); // [!code skip] ``` From d43da87cc370cdcce24b8ebcf42d6977e9ca5bb9 Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 18:03:06 +0100 Subject: [PATCH 05/11] skipped-code: read bare `...` only in JSON, and record directive indents in the parser A language with no entry in the comment table may still have comments (F#, Elixir), so bare `...` there stays code. The notation parser now keeps each directive's indentation, which drops the skip plugin's own hook, and it trims aliases once and exits early on blocks whose only `...` is code. Co-Authored-By: Claude Opus 5.5 --- .agents/DECISIONS.md | 2 +- .../content/docs/features/skipped-code.mdx | 6 ++-- packages/starlight-codeblocks/CHANGELOG.md | 2 +- .../src/expressive-code/comments.ts | 8 +++-- .../src/expressive-code/notation.ts | 27 ++++++++++++----- .../src/expressive-code/skipped-code.ts | 30 ++++--------------- packages/starlight-codeblocks/src/options.ts | 2 +- .../test/skipped-code.test.ts | 1 + .../references/readability.md | 4 +-- 9 files changed, 40 insertions(+), 42 deletions(-) diff --git a/.agents/DECISIONS.md b/.agents/DECISIONS.md index 96d1b76..2f4c1be 100644 --- a/.agents/DECISIONS.md +++ b/.agents/DECISIONS.md @@ -96,7 +96,7 @@ The choices that the code does not explain, with the options that were rejected. - **Expandable blocks collapse only in the client**, with `hidden="until-found"`, so a block is complete without JavaScript and find in page reveals lines. Collapsed lines use `content-visibility: hidden` because EC's `all: revert` removes the browser's until-found style. `auto` skips code tabs variants, runnable blocks and collapsible sections; the components remove an `auto` cap. - **The hidden-lines toggle label changes, with no `aria-pressed`**, which would contradict the label. Open hidden lines dim to 0.75 opacity by the user's choice; syntax colours stay at 3:1 or more, and the accessibility page lists it as an exception with `openOpacity: '1'` to turn it off. - **A manual selection leaves out closed hidden lines.** The copy button includes them. *Rejected:* a `copy` handler that adds them (the paste would differ from the selection). -- **Skipped code is the `[!code skip]` directive and its aliases**, written where an author would write `// ...`. The marker is static HTML with no client module, and not a button, as there is nothing to open. It takes the indentation of the directive line, and a directive line at the end of the block puts it after the last line (`endOfBlock` on the directive spec). A dotted rule tells it apart from the dashed hidden lines marker. A line that holds only an alias (`skippedCode.aliases`, default `...`) is the same directive: as a whole comment (`// ...`), or alone in a language with no comment syntax (JSON), so that `...` in Python or YAML stays code. Aliases take no text, so a comment such as `// ... more` stays as written. `[]` in `notation.comments` reads nothing, aliases too, so the docs' `md` source panes keep `...`. *Rejected:* a `skip={range}` attribute (a range names lines, not the gaps between them, and cannot name the end); `:N` as a count of skipped lines that makes line numbers jump (other directives read `:N` as the lines they apply to). +- **Skipped code is the `[!code skip]` directive and its aliases**, written where an author would write `// ...`. The marker is static HTML with no client module, and not a button, as there is nothing to open. It takes the indentation of the directive line, and a directive line at the end of the block puts it after the last line (`endOfBlock` on the directive spec). A dotted rule tells it apart from the dashed hidden lines marker. A line that holds only an alias (`skippedCode.aliases`, default `...`) is the same directive: as a whole comment (`// ...`), or alone in JSON, so that `...` in Python or YAML stays code. Only JSON: a language with no entry in the comment table may still have comments (F#, Elixir). Aliases take no text, so a comment such as `// ... more` stays as written. `[]` in `notation.comments` reads nothing, aliases too, so the docs' `md` source panes keep `...`. *Rejected:* a `skip={range}` attribute (a range names lines, not the gaps between them, and cannot name the end); `:N` as a count of skipped lines that makes line numbers jump (other directives read `:N` as the lines they apply to). ### Copy, run, playgrounds, placeholders diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx index 83aa352..6cb4584 100644 --- a/docs/src/content/docs/features/skipped-code.mdx +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -36,7 +36,7 @@ The first marker replaces the body of the `get` handler and shows the text after | `[!code skip]` | Comment on its own line, or at the end of a line | | `[!code skip] text` | Comment on its own line, or at the end of a line | | `// ...` | Comment that holds only `...`, on its own line. Use the comment syntax of the language, such as `# ...` | -| `...` | On its own line, in a language with no comments, such as JSON | +| `...` | On its own line, in JSON | Put the directive on its own line where the code is left out. The marker takes the place of that line, with the same indentation. At the end of a line, the marker goes above that line. Without text, the marker reads "Code not shown". The text can hold inline code, links and bold text. @@ -86,7 +86,7 @@ export const json = ` -`...` alone on its line is a marker only in languages with no comments. In Python, `...` is code, and in YAML it ends a document, so these blocks keep it. +`...` alone on its line is a marker only in JSON. In Python, `...` is code, and in YAML it ends a document, so these blocks keep it. ### Skip the start of a file @@ -158,7 +158,7 @@ Turn the feature off for the whole site with `skippedCode: false`. The plugin th ## Limitations -- The directive needs a comment. A language with no comments, such as JSON, can use only `...`, so its markers have no text. +- The directive needs a comment. JSON has no comments and can use only `...`, so its markers have no text. - Line numbers do not jump over the skipped code. To start a block at a later number, use the `startLineNumber` attribute of Expressive Code. - The copied code is incomplete, so it can fail to run. Do not use skipped code in a block with a **Run code** or playground button. diff --git a/packages/starlight-codeblocks/CHANGELOG.md b/packages/starlight-codeblocks/CHANGELOG.md index 0f29630..b8d270d 100644 --- a/packages/starlight-codeblocks/CHANGELOG.md +++ b/packages/starlight-codeblocks/CHANGELOG.md @@ -7,7 +7,7 @@ - Markdown plugins: `starlight-codeblocks/markdown` exports a Markdown plugin for each feature that changes Markdown, such as `mdastCodeTabs()`, and `mdastCodeblocks()` for all of them. `codeblocks()` adds only the ones that the Markdown processor does not already list, in the correct order among them. A listed plugin for a feature that is off stops the build (#36) - Split diff: a **Unified** and **Split** switch in 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 GitHub pull request does. `splitDiff.view`, `splitDiff.switch` and `splitDiff.sync` set the start view, remove the switch and stop it syncing across the page (#37) - Untitled blocks with title bar controls use the tab bar colours of titled blocks (#37) -- Skipped code: `[!code skip]` shows a marker in place of code that a block leaves out, at the indentation of its line. The text after the directive goes in the marker, else it reads "Code not shown". A directive on its own line at the end of a block puts the marker after the last line. A comment that holds only `...`, such as `// ...`, is the same, and so is `...` alone on its line in a language with no comments, such as JSON. `skippedCode.aliases` changes these. The copied code leaves out the marker. `skippedCode: false` turns it off (#28) +- Skipped code: `[!code skip]` shows a marker in place of code that a block leaves out, at the indentation of its line. The text after the directive goes in the marker, else it reads "Code not shown". A directive on its own line at the end of a block puts the marker after the last line. A comment that holds only `...`, such as `// ...`, is the same, and so is `...` alone on its line in JSON. `skippedCode.aliases` changes these. The copied code leaves out the marker. `skippedCode: false` turns it off (#28) ## 1.4.1 diff --git a/packages/starlight-codeblocks/src/expressive-code/comments.ts b/packages/starlight-codeblocks/src/expressive-code/comments.ts index c31ed8b..de6623f 100644 --- a/packages/starlight-codeblocks/src/expressive-code/comments.ts +++ b/packages/starlight-codeblocks/src/expressive-code/comments.ts @@ -35,7 +35,10 @@ export interface CommentSyntax { close?: string; } -/** `undefined` for a language with no comment syntax. `[]` for a language whose comments the site turned off. */ +/** + * `undefined` for JSON, which has no comment syntax. + * `[]` for a language whose comments the site turned off, or that has no entry. + */ export function commentSyntaxFor( language: string, overrides: Record = {}, @@ -46,7 +49,8 @@ export function commentSyntaxFor( const own = (syntaxes: Record) => keys.map((k) => (Object.hasOwn(syntaxes, k) ? syntaxes[k] : undefined)).find(Boolean); const syntax = own(overrides) ?? own(defaultCommentSyntax); - return syntax?.map((entry) => { + if (!syntax && keys.includes('json')) return undefined; + return (syntax ?? []).map((entry) => { const [open = '', close] = entry.trim().split(/\s+/); return { open, close }; }); diff --git a/packages/starlight-codeblocks/src/expressive-code/notation.ts b/packages/starlight-codeblocks/src/expressive-code/notation.ts index 5bca320..7aa4743 100644 --- a/packages/starlight-codeblocks/src/expressive-code/notation.ts +++ b/packages/starlight-codeblocks/src/expressive-code/notation.ts @@ -9,7 +9,7 @@ export interface DirectiveSpec { endOfBlock?: boolean; /** * A line that holds only one of these, in a comment, is read as the directive. - * In a language with no comment syntax, the alias alone on its line. + * In JSON, which has no comments, the alias alone on its line. */ aliases?: string[]; /** For the directives reference page. */ @@ -38,6 +38,8 @@ export interface Directive { sourceLine: number; /** The directive comes after its line: see `DirectiveSpec.endOfBlock`. */ after?: boolean; + /** The leading whitespace of the directive's source line. */ + indent?: string; } const wordChar = /[\w$]/; @@ -311,7 +313,7 @@ function aliasOf(line: string, syntaxes: CommentSyntax[] | undefined, aliases: [ /** * Parses every line, and moves the directives of removed lines to the line below them. - * `syntaxes` is `undefined` for a language with no comment syntax: only aliases apply there. + * `syntaxes` is `undefined` for JSON, which has no comments: only aliases apply there. */ export function parseNotation( lines: string[], @@ -321,12 +323,17 @@ export function parseNotation( diff = false, ): ParsedLine[] { const aliases = Object.entries(specs).flatMap(([name, spec]) => - (spec.aliases ?? []).map((alias): [string, string] => [alias.trim(), name]), + (spec.aliases ?? []).map((alias): [string, string] => [alias, name]), ); const parsed = lines.map((text, i): ParsedLine => { - const name = aliases.length > 0 ? aliasOf(text, syntaxes, aliases) : undefined; - if (name) return { text: '', removed: true, directives: [{ name, count: 1, args: [], sourceLine: i + 1 }] }; - return syntaxes ? parseLine(text, syntaxes, specs, report, i + 1, diff) : { text, removed: false, directives: [] }; + const name = aliasOf(text, syntaxes, aliases); + const line: ParsedLine = name + ? { text: '', removed: true, directives: [{ name, count: 1, args: [], sourceLine: i + 1 }] } + : syntaxes + ? parseLine(text, syntaxes, specs, report, i + 1, diff) + : { text, removed: false, directives: [] }; + for (const directive of line.directives) directive.indent = text.match(/^\s*/)?.[0]; + return line; }); let pending: Directive[] = []; for (const line of parsed) { @@ -476,9 +483,11 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl {}, ...config.plugins.map((plugin) => (plugin as CodeblocksPlugin).directives ?? {}), ); - const aliases = Object.values(specs).flatMap((spec) => spec.aliases ?? []); const hasDirectives = syntaxes !== undefined && /\[\\?!/.test(codeBlock.code); - if (!hasDirectives && !aliases.some((alias) => codeBlock.code.includes(alias.trim()))) return; + const mayHaveAliases = Object.values(specs).some((spec) => + spec.aliases?.some((alias) => codeBlock.code.includes(alias)), + ); + if (!hasDirectives && !mayHaveAliases) return; const lines = codeBlock.getLines(); const parsed = parseNotation( lines.map((line) => line.text), @@ -488,6 +497,8 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl // The text markers plugin reads the `useDiffSyntax` meta option only in `preprocessMetadata`. codeBlock.metaOptions.getBoolean('useDiffSyntax') ?? Boolean(codeBlock.props.useDiffSyntax), ); + // `...` as spread or rest syntax passes the alias check above. + if (!hasDirectives && !parsed.some((line) => line.removed)) return; const visible = lines.filter((_, i) => !parsed[i]?.removed); const marks = parsed.flatMap(({ directives }, i) => directives diff --git a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts index 0ceea72..5800854 100644 --- a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts +++ b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts @@ -1,15 +1,9 @@ -import { - AttachedPluginData, - onBackground, - PluginStyleSettings, - setAlpha, - type UnresolvedStyleValue, -} from '@expressive-code/core'; +import { onBackground, PluginStyleSettings, setAlpha, type UnresolvedStyleValue } from '@expressive-code/core'; import { h, select } from '@expressive-code/core/hast'; import { uiTexts } from '../translations.ts'; import { type CodeblocksPlugin, insertAfter, insertBefore, lineElement } from './core.ts'; import { inlineMarkdown } from './inline-markdown.ts'; -import { getDirectives, getRenderedDirectives } from './notation.ts'; +import { getRenderedDirectives } from './notation.ts'; import { PREFIX, solidCodeBackground } from './styles.ts'; export interface SkippedCodeStyleSettings { @@ -33,9 +27,6 @@ const styleSettings = new PluginStyleSettings({ }, }); -/** The indentation of each directive's source line, by source line. */ -const indentData = new AttachedPluginData>(() => new Map()); - export interface SkippedCodeSettings { /** Lines that stand for `[!code skip]`, alone or as the whole of a comment. */ aliases?: string[]; @@ -49,7 +40,7 @@ export function pluginSkippedCode({ aliases = ['...'] }: SkippedCodeSettings = { 'code skip': { text: true, endOfBlock: true, - aliases, + aliases: aliases.map((alias) => alias.trim()), docs: { description: 'Shows a marker in place of code that the block leaves out.', args: 'Optional. The text of the marker.', @@ -90,23 +81,14 @@ export function pluginSkippedCode({ aliases = ['...'] }: SkippedCodeSettings = { } `, hooks: { - // The notation plugin deletes the directive's own line in `preprocessCode`. - preprocessMetadata({ codeBlock }) { - const lines = codeBlock.getLines(); - const indents = indentData.getOrCreateFor(codeBlock); - for (const { sourceLine } of getDirectives(codeBlock, 'code skip')) { - indents.set(sourceLine, lines[sourceLine - 1]?.text.match(/^\s*/)?.[0] ?? ''); - } - }, postprocessRenderedBlock(context) { - const code = select('pre > code', context.renderData.blockAst); + const directives = getRenderedDirectives(context, 'code skip'); + const code = directives.length > 0 && select('pre > code', context.renderData.blockAst); if (!code) return; const say = uiTexts(context.locale); - const indents = indentData.getOrCreateFor(context.codeBlock); - for (const { lines, text, after, sourceLine } of getRenderedDirectives(context, 'code skip')) { + for (const { lines, text, after, indent } of directives) { const line = lines[0] && lineElement(lines[0]); if (!line) continue; - const indent = indents.get(sourceLine); const marker = h('div', { class: `${PREFIX}-skip-marker` }, [ ...(indent ? [h('span', { class: `${PREFIX}-skip-indent` }, indent)] : []), h('span', { class: `${PREFIX}-skip-text` }, text ? inlineMarkdown(text) : say('skippedCode.marker')), diff --git a/packages/starlight-codeblocks/src/options.ts b/packages/starlight-codeblocks/src/options.ts index 7d5f872..8f3efa3 100644 --- a/packages/starlight-codeblocks/src/options.ts +++ b/packages/starlight-codeblocks/src/options.ts @@ -328,7 +328,7 @@ export const optionsReference: Record = { type: 'string[]', default: ['...'], description: - 'Lines that stand for `[!code skip]`: a comment that holds only an alias, or the alias alone on its line in a language with no comments, such as JSON. `[]` turns them off.', + 'Lines that stand for `[!code skip]`: a comment that holds only an alias, or the alias alone on its line in JSON, which has no comments. `[]` turns them off.', valid: (value) => isStringArray(value) && (value as string[]).every((alias) => alias.trim() !== ''), }, }, diff --git a/packages/starlight-codeblocks/test/skipped-code.test.ts b/packages/starlight-codeblocks/test/skipped-code.test.ts index e112b7a..b3c9c34 100644 --- a/packages/starlight-codeblocks/test/skipped-code.test.ts +++ b/packages/starlight-codeblocks/test/skipped-code.test.ts @@ -51,6 +51,7 @@ test('leaves `...` that is code, or that has more text, as written', async () => block('yaml', 'a: 1', '...'), block('js', 'f(...args) // ...', '// ... more', '// [...]'), block('json', '[', ' "..."', ']'), + block('fsharp', 'let f () =', ' ...'), ]) { expect(marker((await render(md)).html)).toEqual([]); } diff --git a/skills/starlight-codeblocks/references/readability.md b/skills/starlight-codeblocks/references/readability.md index 39a9563..dfbe6d5 100644 --- a/skills/starlight-codeblocks/references/readability.md +++ b/skills/starlight-codeblocks/references/readability.md @@ -50,7 +50,7 @@ Use where an example shows part of a file and leaves code out. A marker takes th | `[!code skip]` | Comment on its own line where the code is left out, or at the end of the line below that place | | `[!code skip] text` | The same, with `text` on the marker in place of "Code not shown" | | `// ...` | Comment that holds only `...`, on its own line, in the comment syntax of the language (`# ...`) | -| `...` | On its own line, in a language with no comments, such as JSON | +| `...` | On its own line, in JSON | ```js app.get('/users', async (req, res) => { @@ -64,7 +64,7 @@ app.get('/users', async (req, res) => { - The copied code has no marker, and no skipped code. Do not use it in a block with a playground or the **Run code** button. - Line numbers do not jump over the marker. - A comment with other text, such as `// ... more`, stays in the code. For a marker with text, use `[!code skip] text`. -- `...` alone on its line is a marker only in languages with no comments. In Python and YAML, it stays as code. +- `...` alone on its line is a marker only in JSON. In Python and YAML, it stays as code. - Option: `skippedCode.aliases` (default `['...']`) sets the lines that are the same as `[!code skip]`. `[]` turns them off. `skippedCode: false` leaves `[!code skip]` and `...` in the code. ## Expandable blocks From 61e0f498473421533be0227c44df7e0f2113456f Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 18:28:17 +0100 Subject: [PATCH 06/11] skipped-code: make the `...` aliases opt-in, and fix markers in hidden runs, diffs and at the end of a block - `skippedCode.aliases` defaults to `[]`, because `// ...` lines that leave the code move the ranges of existing pages. The docs, the skill and the changelog explain the opt-in and what it changes. - A marker between hidden lines hides and shows with them. - Markers at the end of a block keep their source order, and go after the last line of code, not after output lines. - In diff blocks, a skip line with a `+` or `-` prefix is read, at the indentation that readers see. - Hidden lines and skipped code share their marker colours and styles, so skipped code also clears the copy button on touch screens. - `commentSyntaxFor()` returns an array again, and `hasNoComments()` tells JSON apart. Co-Authored-By: Claude Opus 5.5 --- .agents/DECISIONS.md | 2 +- docs/astro.config.mjs | 1 + .../docs/features/code-walkthrough.mdx | 1 + .../content/docs/features/skipped-code.mdx | 39 +++--- packages/starlight-codeblocks/CHANGELOG.md | 2 +- .../src/client/hidden-lines.ts | 6 +- .../src/expressive-code/brackets.ts | 2 +- .../src/expressive-code/comments.ts | 25 ++-- .../src/expressive-code/hidden-lines.ts | 35 +----- .../src/expressive-code/notation.ts | 113 +++++++++++------- .../src/expressive-code/skipped-code.ts | 70 ++++------- .../src/expressive-code/styles.ts | 49 ++++++++ packages/starlight-codeblocks/src/options.ts | 6 +- .../test/brackets.test.ts | 10 +- .../test/notation.test.ts | 21 ++-- .../starlight-codeblocks/test/options.test.ts | 2 +- .../test/skipped-code.test.ts | 47 ++++++-- skills/starlight-codeblocks/SKILL.md | 3 +- .../references/configuration.md | 2 +- .../references/explain-code.md | 2 +- .../references/readability.md | 12 +- 21 files changed, 266 insertions(+), 184 deletions(-) diff --git a/.agents/DECISIONS.md b/.agents/DECISIONS.md index 2f4c1be..eff7743 100644 --- a/.agents/DECISIONS.md +++ b/.agents/DECISIONS.md @@ -96,7 +96,7 @@ The choices that the code does not explain, with the options that were rejected. - **Expandable blocks collapse only in the client**, with `hidden="until-found"`, so a block is complete without JavaScript and find in page reveals lines. Collapsed lines use `content-visibility: hidden` because EC's `all: revert` removes the browser's until-found style. `auto` skips code tabs variants, runnable blocks and collapsible sections; the components remove an `auto` cap. - **The hidden-lines toggle label changes, with no `aria-pressed`**, which would contradict the label. Open hidden lines dim to 0.75 opacity by the user's choice; syntax colours stay at 3:1 or more, and the accessibility page lists it as an exception with `openOpacity: '1'` to turn it off. - **A manual selection leaves out closed hidden lines.** The copy button includes them. *Rejected:* a `copy` handler that adds them (the paste would differ from the selection). -- **Skipped code is the `[!code skip]` directive and its aliases**, written where an author would write `// ...`. The marker is static HTML with no client module, and not a button, as there is nothing to open. It takes the indentation of the directive line, and a directive line at the end of the block puts it after the last line (`endOfBlock` on the directive spec). A dotted rule tells it apart from the dashed hidden lines marker. A line that holds only an alias (`skippedCode.aliases`, default `...`) is the same directive: as a whole comment (`// ...`), or alone in JSON, so that `...` in Python or YAML stays code. Only JSON: a language with no entry in the comment table may still have comments (F#, Elixir). Aliases take no text, so a comment such as `// ... more` stays as written. `[]` in `notation.comments` reads nothing, aliases too, so the docs' `md` source panes keep `...`. *Rejected:* a `skip={range}` attribute (a range names lines, not the gaps between them, and cannot name the end); `:N` as a count of skipped lines that makes line numbers jump (other directives read `:N` as the lines they apply to). +- **Skipped code is the `[!code skip]` directive and its aliases**, written where an author would write `// ...`. The marker is static HTML with no client module, and not a button, as there is nothing to open. It takes the indentation of the directive line, and a directive line at the end of the block puts it after the last line (`endOfBlock` on the directive spec). The badge text says what the marker is, so the dotted rule is decoration and stays as faint as the dashed hidden lines rule. A line that holds only an alias (`skippedCode.aliases`) is the same directive: as a whole comment (`// ...`), or alone in JSON, so that `...` in Python or YAML stays code. Aliases are off by default: `// ...` lines leave the code, which moves every range after them and stops walkthrough animations, on pages that never asked for the feature. With aliases on, a comment with more text (`// ... and so on`) keeps a `// ...` as code; no per-block switch. Only JSON: a language with no entry in the comment table may still have comments (F#, Elixir). Aliases take no text, so a comment such as `// ... more` stays as written. `[]` in `notation.comments` reads nothing, aliases too, so the docs' `md` source panes keep `...`. *Rejected:* a `skip={range}` attribute (a range names lines, not the gaps between them, and cannot name the end); `:N` as a count of skipped lines that makes line numbers jump (other directives read `:N` as the lines they apply to). ### Copy, run, playgrounds, placeholders diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index f678ec6..0afb577 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -38,6 +38,7 @@ export default defineConfig({ codeblocks({ // Markdown blocks on this site show the source that authors write, so their directives must stay as text. notation: { comments: { md: [], markdown: [], mdx: [] } }, + skippedCode: { aliases: ['...'] }, shellCopy: { prompts: ['$ ', '> ', 'PS> '] }, swatches: { prose: true }, fileIcons: { diff --git a/docs/src/content/docs/features/code-walkthrough.mdx b/docs/src/content/docs/features/code-walkthrough.mdx index 71f9a7a..c24c7a3 100644 --- a/docs/src/content/docs/features/code-walkthrough.mdx +++ b/docs/src/content/docs/features/code-walkthrough.mdx @@ -247,6 +247,7 @@ def greet(name, greeting="Hello"): - 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. - A step with removed or added lines changes without the animation, so its diff colours and `+` and `-` markers stay in place. + - A step with a callout, a hidden lines marker or a skipped code marker changes without the animation. The animation does not have the height of these rows. ## Options diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx index 6cb4584..f97fa20 100644 --- a/docs/src/content/docs/features/skipped-code.mdx +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -7,7 +7,7 @@ import { LinkCard } from '@astrojs/starlight/components'; import Example from '../../../components/Example.astro'; import Options from '../../../components/Options.astro'; -An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. Skipped code puts a marker in its place, which looks different from the code and is not part of the copied text. Write the `[!code skip]` directive, with optional text, or keep the `// ...` comment. +An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. Skipped code puts a marker in its place, which looks different from the code and is not part of the copied text. Write the `[!code skip]` directive, with optional text. A site can also [read its `// ...` comments as markers](#read---as-markers). export const basic = ` \`\`\`js title="routes.js" @@ -35,15 +35,11 @@ The first marker replaces the body of the `get` handler and shows the text after |---|---| | `[!code skip]` | Comment on its own line, or at the end of a line | | `[!code skip] text` | Comment on its own line, or at the end of a line | -| `// ...` | Comment that holds only `...`, on its own line. Use the comment syntax of the language, such as `# ...` | -| `...` | On its own line, in JSON | +| `// ...` | Comment that holds only `...`, on its own line, with `aliases: ['...']`. Use the comment syntax of the language, such as `# ...` | +| `...` | On its own line, in JSON, with `aliases: ['...']` | Put the directive on its own line where the code is left out. The marker takes the place of that line, with the same indentation. At the end of a line, the marker goes above that line. Without text, the marker reads "Code not shown". The text can hold inline code, links and bold text. -:::tip -A comment that holds only `...`, such as `// ...` or `# ...`, is the same as `[!code skip]`. For a marker with text, use `[!code skip] text`. A comment with other text, such as `// ... more`, stays in the code. -::: - ## Examples ### Skip code without text @@ -69,7 +65,7 @@ export class Cache { ### Skip code in JSON -JSON has no comments. On its own line, `...` is the marker: +JSON has no comments, so the directive cannot go in a JSON block. With the `...` alias, `...` on its own line is the marker. This site sets the alias: export const json = ` \`\`\`json title="package.json" @@ -86,7 +82,7 @@ export const json = ` -`...` alone on its line is a marker only in JSON. In Python, `...` is code, and in YAML it ends a document, so these blocks keep it. +`...` alone on its line is a marker only in JSON. In Python, `...` is code, and in YAML it ends a document, so these blocks keep it. Without the alias, use `jsonc`, which has comments. ### Skip the start of a file @@ -142,23 +138,38 @@ volumes: -To add an alias, such as `…`, or to change `...`, set `aliases`: +### Read `// ...` as markers + +Many pages already use `// ...` for code that they leave out. By default, these comments stay in the code as written. To read them as markers, set `aliases`: ```js title="astro.config.mjs" codeblocks({ - skippedCode: { aliases: ['...', '…'] }, + skippedCode: { aliases: ['...'] }, }); ``` -A language with `[]` in `notation.comments` reads no directives, so `...` stays in its blocks too. +A comment with only an alias in it is then the same as `[!code skip]`, such as `// ...`, `# ...` or `/* ... */`. It must be alone on its line. In JSON, `...` alone on its line is a marker. Add more aliases to the list, such as `'…'`. + +:::caution +The aliases change existing pages. Check the pages that use `// ...` after you set them: + +- The `// ...` lines leave the code, so line ranges count different lines. In a block with `// ...` on line 2, `{4}` marks the line that was line 5. This applies to every range attribute, such as `ins={4}` and `focus={4}`. +- The `// ...` lines also leave the copied code. +- A [code walkthrough](/starlight-codeblocks/features/code-walkthrough/) or [scrollycoding](/starlight-codeblocks/features/scrollycoding/) step with a marker changes without the animation. +::: + +To keep `// ...` as code in one block, add text to the comment, such as `// ... and so on`. A comment with text other than an alias stays in the code. A language with `[]` in `notation.comments` reads no directives and no aliases. + +### Turn the feature off -Turn the feature off for the whole site with `skippedCode: false`. The plugin then does not know the `[!code skip]` directive. It leaves the directive in the code as written, and logs a build warning. `...` lines also stay as written. +Turn the feature off for the whole site with `skippedCode: false`. The plugin then does not know the `[!code skip]` directive. It leaves the directive in the code as written, and logs a build warning. ## Limitations -- The directive needs a comment. JSON has no comments and can use only `...`, so its markers have no text. +- The directive needs a comment. JSON has no comments and can use only the `...` alias, so its markers have no text. +- A code walkthrough or scrollycoding step with a marker changes without the animation. The animation does not have the height of the marker. - Line numbers do not jump over the skipped code. To start a block at a later number, use the `startLineNumber` attribute of Expressive Code. - The copied code is incomplete, so it can fail to run. Do not use skipped code in a block with a **Run code** or playground button. diff --git a/packages/starlight-codeblocks/CHANGELOG.md b/packages/starlight-codeblocks/CHANGELOG.md index b8d270d..d3d6871 100644 --- a/packages/starlight-codeblocks/CHANGELOG.md +++ b/packages/starlight-codeblocks/CHANGELOG.md @@ -7,7 +7,7 @@ - Markdown plugins: `starlight-codeblocks/markdown` exports a Markdown plugin for each feature that changes Markdown, such as `mdastCodeTabs()`, and `mdastCodeblocks()` for all of them. `codeblocks()` adds only the ones that the Markdown processor does not already list, in the correct order among them. A listed plugin for a feature that is off stops the build (#36) - Split diff: a **Unified** and **Split** switch in 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 GitHub pull request does. `splitDiff.view`, `splitDiff.switch` and `splitDiff.sync` set the start view, remove the switch and stop it syncing across the page (#37) - Untitled blocks with title bar controls use the tab bar colours of titled blocks (#37) -- Skipped code: `[!code skip]` shows a marker in place of code that a block leaves out, at the indentation of its line. The text after the directive goes in the marker, else it reads "Code not shown". A directive on its own line at the end of a block puts the marker after the last line. A comment that holds only `...`, such as `// ...`, is the same, and so is `...` alone on its line in JSON. `skippedCode.aliases` changes these. The copied code leaves out the marker. `skippedCode: false` turns it off (#28) +- Skipped code: `[!code skip]` shows a marker in place of code that a block leaves out, at the indentation of its line. The text after the directive goes in the marker, else it reads "Code not shown". A directive on its own line at the end of a block puts the marker after the last line. `skippedCode.aliases: ['...']` also reads a comment that holds only `...`, such as `// ...`, and `...` alone on its line in JSON. The aliases are off by default, because they change the line ranges of existing pages. The copied code leaves out the marker. `skippedCode: false` turns it off (#28) ## 1.4.1 diff --git a/packages/starlight-codeblocks/src/client/hidden-lines.ts b/packages/starlight-codeblocks/src/client/hidden-lines.ts index b8cc439..4bf4668 100644 --- a/packages/starlight-codeblocks/src/client/hidden-lines.ts +++ b/packages/starlight-codeblocks/src/client/hidden-lines.ts @@ -17,7 +17,11 @@ function setRun(block: Element, marker: Element, open: boolean) { line.nextElementSibling.classList.toggle(OPEN, open); // Opens a collapsed expandable block or collapsible section that holds the line. if (open && line) unhide(line); - for (let el = line?.previousElementSibling; el?.classList.contains('scb-callout'); el = el.previousElementSibling) { + for ( + let el = line?.previousElementSibling; + el?.matches('.scb-callout, .scb-skip-marker'); + el = el.previousElementSibling + ) { el.classList.toggle(OPEN, open); } } diff --git a/packages/starlight-codeblocks/src/expressive-code/brackets.ts b/packages/starlight-codeblocks/src/expressive-code/brackets.ts index 86c8876..669fe81 100644 --- a/packages/starlight-codeblocks/src/expressive-code/brackets.ts +++ b/packages/starlight-codeblocks/src/expressive-code/brackets.ts @@ -213,7 +213,7 @@ export function pluginBrackets({ const lines = codeBlock.getLines(); const matches = findBrackets( lines.map((line) => line.text), - commentSyntaxFor(codeBlock.language, comments) ?? [], + commentSyntaxFor(codeBlock.language, comments), charLiteralLanguages.has(codeBlock.language), ); for (const { line, column, depth, pairId } of matches) { diff --git a/packages/starlight-codeblocks/src/expressive-code/comments.ts b/packages/starlight-codeblocks/src/expressive-code/comments.ts index de6623f..1496e38 100644 --- a/packages/starlight-codeblocks/src/expressive-code/comments.ts +++ b/packages/starlight-codeblocks/src/expressive-code/comments.ts @@ -35,23 +35,26 @@ export interface CommentSyntax { close?: string; } -/** - * `undefined` for JSON, which has no comment syntax. - * `[]` for a language whose comments the site turned off, or that has no entry. - */ -export function commentSyntaxFor( - language: string, - overrides: Record = {}, -): CommentSyntax[] | undefined { +function commentEntry(language: string, overrides: Record) { const key = language.toLowerCase(); const info = bundledLanguage(key); const keys = [key, ...(info ? [info.id, ...(info.aliases ?? [])] : [])]; const own = (syntaxes: Record) => keys.map((k) => (Object.hasOwn(syntaxes, k) ? syntaxes[k] : undefined)).find(Boolean); - const syntax = own(overrides) ?? own(defaultCommentSyntax); - if (!syntax && keys.includes('json')) return undefined; - return (syntax ?? []).map((entry) => { + return { keys, syntax: own(overrides) ?? own(defaultCommentSyntax) }; +} + +export function commentSyntaxFor(language: string, overrides: Record = {}): CommentSyntax[] { + return (commentEntry(language, overrides).syntax ?? []).map((entry) => { const [open = '', close] = entry.trim().split(/\s+/); return { open, close }; }); } + +/** + * JSON, unless the site gives it a comment syntax. Other languages with no entry may still have comments (F#, Elixir). + */ +export function hasNoComments(language: string, overrides: Record = {}) { + const { keys, syntax } = commentEntry(language, overrides); + return !syntax && keys.includes('json'); +} diff --git a/packages/starlight-codeblocks/src/expressive-code/hidden-lines.ts b/packages/starlight-codeblocks/src/expressive-code/hidden-lines.ts index ff7931a..3d348f5 100644 --- a/packages/starlight-codeblocks/src/expressive-code/hidden-lines.ts +++ b/packages/starlight-codeblocks/src/expressive-code/hidden-lines.ts @@ -2,9 +2,7 @@ import { AttachedPluginData, type ExpressiveCodeBlock, type ExpressiveCodeLine, - onBackground, PluginStyleSettings, - type StyleResolverFn, setAlpha, type UnresolvedStyleValue, } from '@expressive-code/core'; @@ -13,7 +11,7 @@ import { clientJsModules } from '../client-modules.ts'; import { uiTexts } from '../translations.ts'; import { addTitleBarControl, blockUid, type CodeblocksPlugin, insertBefore, lineElement } from './core.ts'; import { markedLines } from './notation.ts'; -import { PREFIX, solidCodeBackground, solidCodeForeground } from './styles.ts'; +import { markerColours, markerStyles, PREFIX, solidCodeForeground } from './styles.ts'; export interface HiddenLinesStyleSettings { badgeBackground: UnresolvedStyleValue; @@ -33,9 +31,7 @@ declare module '@expressive-code/core' { const styleSettings = new PluginStyleSettings({ defaultValues: { codeblocksHiddenLines: { - badgeBackground: (context: Parameters[0]) => - onBackground(setAlpha(context.resolveSetting('codeblocks.mutedForeground'), 0.1), solidCodeBackground(context)), - rule: ({ resolveSetting }) => setAlpha(resolveSetting('codeblocks.mutedForeground'), 0.35), + ...markerColours, ruleHover: ({ resolveSetting }) => resolveSetting('codeblocks.mutedForeground'), ruleOpen: ({ resolveSetting }) => setAlpha(resolveSetting('codeblocks.mutedForeground'), 0.22), openBackground: (context) => setAlpha(solidCodeForeground(context), 0.04), @@ -74,46 +70,21 @@ export function pluginHiddenLines(): CodeblocksPlugin { background: ${cssVar('codeblocksHiddenLines.openBackground')}; opacity: ${cssVar('codeblocksHiddenLines.openOpacity')}; } +${markerStyles(cssVar, `${PREFIX}-hidden-marker`, `${PREFIX}-hidden-marker span`, 'codeblocksHiddenLines', 'dashed')} .${PREFIX}-hidden-marker { - display: flex; - align-items: center; width: 100%; - position: relative; - margin: 2px 0; padding: 0; border: 0; background: none; - color: ${cssVar('codeblocks.mutedForeground')}; cursor: pointer; font: inherit; text-align: left; - user-select: none; - -webkit-user-select: none; -} -.${PREFIX}-hidden-marker::before { - content: ''; - position: absolute; - top: 50%; - inset-inline: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}) ${cssVar('codePaddingInline')}; - border-top: 1px dashed ${cssVar('codeblocksHiddenLines.rule')}; - transform: translateY(-50%); -} -/* Where the copy button always shows, it sits over the end of the first line. */ -@media (hover: none) { - .${PREFIX}-hidden-marker:first-child::before { inset-inline-end: calc(${cssVar('codePaddingInline')} + 2.5rem); } } .${PREFIX}-hidden-marker span { - position: relative; - z-index: 1; display: inline-flex; align-items: center; /* The gutter width is in ch of the code font; the division undoes this span's smaller font size. */ margin-inline-start: calc(var(--scb-gutter, 0px) / 0.8125 + ${cssVar('codePaddingInline')}); - padding: 0.05em 0.65em; - border-radius: 999px; - background: ${cssVar('codeblocksHiddenLines.badgeBackground')}; - font-size: 0.8125em; - line-height: 1.6; } .${PREFIX}-hidden-marker:hover, .${PREFIX}-hidden-marker:focus-visible { color: ${cssVar('codeForeground')}; diff --git a/packages/starlight-codeblocks/src/expressive-code/notation.ts b/packages/starlight-codeblocks/src/expressive-code/notation.ts index 7aa4743..3ae24fc 100644 --- a/packages/starlight-codeblocks/src/expressive-code/notation.ts +++ b/packages/starlight-codeblocks/src/expressive-code/notation.ts @@ -1,5 +1,5 @@ import { AttachedPluginData, type ExpressiveCodeBlock, type ExpressiveCodeLine } from '@expressive-code/core'; -import { type CommentSyntax, commentSyntaxFor } from './comments.ts'; +import { type CommentSyntax, commentSyntaxFor, hasNoComments } from './comments.ts'; import { type CodeblocksPlugin, lineData, lineElement, numberedLines, resolveRange, warn } from './core.ts'; export interface DirectiveSpec { @@ -7,10 +7,7 @@ export interface DirectiveSpec { text?: boolean; /** On a line of its own at the end of the block, the directive applies after the last line, with `after`. */ endOfBlock?: boolean; - /** - * A line that holds only one of these, in a comment, is read as the directive. - * In JSON, which has no comments, the alias alone on its line. - */ + /** A line that holds only one of these, in a comment, or alone in JSON, is read as the directive. */ aliases?: string[]; /** For the directives reference page. */ docs?: { @@ -300,40 +297,54 @@ export function parseLine( return { text: newText, removed: false, directives }; } -/** The name of the directive whose alias is all of `line`, or all of a comment that is all of `line`. */ -function aliasOf(line: string, syntaxes: CommentSyntax[] | undefined, aliases: [alias: string, name: string][]) { +type Aliases = [alias: string, name: string][]; + +const diffPrefix = /^[+-](?![+-])/; + +/** + * The name of the directive whose alias is all of `line`, or all of a comment that is all of `line`. + * With `bare`, for a language with no comments, the alias alone on the line. + */ +function aliasOf(line: string, syntaxes: CommentSyntax[], bare: boolean, aliases: Aliases) { + if (aliases.length === 0) return undefined; const text = line.trim(); - const bodies = syntaxes - ? syntaxes + const bodies = bare + ? [text] + : syntaxes .filter(({ open, close }) => text.startsWith(open) && (!close || text.endsWith(close))) - .map(({ open, close }) => text.slice(open.length, close ? -close.length : undefined).trim()) - : [text]; + .map(({ open, close }) => text.slice(open.length, close ? -close.length : undefined).trim()); return aliases.find(([alias]) => bodies.includes(alias))?.[1]; } +const aliasesOf = (specs: DirectiveSpecs): Aliases => + Object.entries(specs).flatMap(([name, spec]) => (spec.aliases ?? []).map((alias): [string, string] => [alias, name])); + /** * Parses every line, and moves the directives of removed lines to the line below them. - * `syntaxes` is `undefined` for JSON, which has no comments: only aliases apply there. + * With `bare`, for a language with no comments, only aliases apply. */ export function parseNotation( lines: string[], - syntaxes: CommentSyntax[] | undefined, + syntaxes: CommentSyntax[], specs: DirectiveSpecs, report: Report, diff = false, + bare = false, ): ParsedLine[] { - const aliases = Object.entries(specs).flatMap(([name, spec]) => - (spec.aliases ?? []).map((alias): [string, string] => [alias, name]), - ); + const aliases = aliasesOf(specs); + const unprefixed = (text: string) => (diff ? text.replace(diffPrefix, '') : text); const parsed = lines.map((text, i): ParsedLine => { - const name = aliasOf(text, syntaxes, aliases); - const line: ParsedLine = name - ? { text: '', removed: true, directives: [{ name, count: 1, args: [], sourceLine: i + 1 }] } - : syntaxes - ? parseLine(text, syntaxes, specs, report, i + 1, diff) - : { text, removed: false, directives: [] }; - for (const directive of line.directives) directive.indent = text.match(/^\s*/)?.[0]; - return line; + const name = aliasOf(unprefixed(text), syntaxes, bare, aliases); + if (name) return { text: '', removed: true, directives: [{ name, count: 1, args: [], sourceLine: i + 1 }] }; + if (syntaxes.length === 0) return { text, removed: false, directives: [] }; + return parseLine(text, syntaxes, specs, report, i + 1, diff); + }); + // Expressive Code's diff syntax removes the prefix and the indentation that every line shares. + const columns = diff ? diffColumns(lines.filter((_, i) => !parsed[i]?.removed)) : undefined; + parsed.forEach((line, i) => { + const text = lines[i] as string; + const indent = text.slice(columns?.(text) ?? 0).match(/^\s*/)?.[0]; + for (const directive of line.directives) directive.indent = indent; }); let pending: Directive[] = []; for (const line of parsed) { @@ -478,27 +489,29 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl preprocessLanguage(context) { const { codeBlock, config } = context; const syntaxes = commentSyntaxFor(codeBlock.language, comments); - if (syntaxes?.length === 0) return; + const bare = hasNoComments(codeBlock.language, comments); + if (syntaxes.length === 0 && !bare) return; const specs: DirectiveSpecs = Object.assign( {}, ...config.plugins.map((plugin) => (plugin as CodeblocksPlugin).directives ?? {}), ); - const hasDirectives = syntaxes !== undefined && /\[\\?!/.test(codeBlock.code); - const mayHaveAliases = Object.values(specs).some((spec) => - spec.aliases?.some((alias) => codeBlock.code.includes(alias)), - ); - if (!hasDirectives && !mayHaveAliases) return; const lines = codeBlock.getLines(); + // The text markers plugin reads the `useDiffSyntax` meta option only in `preprocessMetadata`. + const diff = codeBlock.metaOptions.getBoolean('useDiffSyntax') ?? Boolean(codeBlock.props.useDiffSyntax); + const aliases = aliasesOf(specs); + const hasDirectives = syntaxes.length > 0 && /\[\\?!/.test(codeBlock.code); + const hasAliases = lines.some((line) => + aliasOf(diff ? line.text.replace(diffPrefix, '') : line.text, syntaxes, bare, aliases), + ); + if (!hasDirectives && !hasAliases) return; const parsed = parseNotation( lines.map((line) => line.text), syntaxes, specs, (message, line) => warn(context, message, line), - // The text markers plugin reads the `useDiffSyntax` meta option only in `preprocessMetadata`. - codeBlock.metaOptions.getBoolean('useDiffSyntax') ?? Boolean(codeBlock.props.useDiffSyntax), + diff, + bare, ); - // `...` as spread or rest syntax passes the alias check above. - if (!hasDirectives && !parsed.some((line) => line.removed)) return; const visible = lines.filter((_, i) => !parsed[i]?.removed); const marks = parsed.flatMap(({ directives }, i) => directives @@ -537,6 +550,11 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl const area = outputSet.has(line) ? output : runSet.has(line) ? run : code; const target = area.indexOf(line); for (const directive of directives) { + // Output and run lines leave the code, so a marker after the block goes after the last line of code. + if (directive.after && area !== code) { + data.directives.push({ ...directive, lines: code.slice(-1) }); + continue; + } data.directives.push({ ...directive, lines: area.slice(target, target + directive.count) }); if (target + directive.count > area.length) { warn(context, `\`:${directive.count}\` runs past the last line of the block.`, directive.sourceLine); @@ -568,7 +586,7 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl const syntaxes = commentSyntaxFor(codeBlock.language, comments); const { removed, specs, diffIndent } = notationData.getOrCreateFor(codeBlock); for (const [line, columns] of diffIndent) line.editText(0, columns, ''); - if (syntaxes?.length && /\[\\?!/.test(codeBlock.code)) { + if (syntaxes.length > 0 && /\[\\?!/.test(codeBlock.code)) { for (const line of codeBlock.getLines()) { // Other plugins can edit lines after the first parse, so parse the current text again. const { text, removed: gone } = parseLine(line.text, syntaxes, specs, () => {}); @@ -588,13 +606,18 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl const diffLine = /^(([+-](?![+-]))?\s*)(.*)$/; -/** The columns that Expressive Code's diff syntax removes from each line, as in its text markers plugin. */ -function diffColumns(lines: readonly ExpressiveCodeLine[]) { - if (lines.slice(0, 4).some((line) => /^([*+-]{3}\s|@@\s|[0-9,]+[acd][0-9,]+\s*$)/.test(line.text))) return undefined; - const parsed = lines.map((line) => line.text.match(diffLine) ?? []); - const indents = parsed.filter((m) => m[3]?.trim()).map((m) => m[1]?.length ?? 0); +/** + * The columns that Expressive Code's diff syntax removes from a line of a block with `lines`, + * as in its text markers plugin. `undefined` for a real diff, which it leaves as written. + */ +function diffColumns(lines: readonly string[]) { + if (lines.slice(0, 4).some((line) => /^([*+-]{3}\s|@@\s|[0-9,]+[acd][0-9,]+\s*$)/.test(line))) return undefined; + const indents = lines + .map((line) => line.match(diffLine) ?? []) + .filter((m) => m[3]?.trim()) + .map((m) => m[1]?.length ?? 0); const min = indents.length > 0 ? Math.min(...indents) : 0; - return new Map(lines.map((line, i) => [line, min || (parsed[i]?.[2] ? 1 : 0)])); + return (line: string) => min || (diffPrefix.test(line) ? 1 : 0); } /** @@ -603,11 +626,11 @@ function diffColumns(lines: readonly ExpressiveCodeLine[]) { */ function diffIndentFix(lines: readonly ExpressiveCodeLine[], visible: readonly ExpressiveCodeLine[]) { const fix = new Map(); - const all = diffColumns(lines); - const seen = diffColumns(visible); + const all = diffColumns(lines.map((line) => line.text)); + const seen = diffColumns(visible.map((line) => line.text)); if (!all || !seen) return fix; - for (const [line, columns] of seen) { - const extra = columns - (all.get(line) ?? 0); + for (const line of visible) { + const extra = seen(line.text) - all(line.text); if (extra > 0) fix.set(line, extra); } return fix; diff --git a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts index 5800854..6140a73 100644 --- a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts +++ b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts @@ -1,10 +1,11 @@ -import { onBackground, PluginStyleSettings, setAlpha, type UnresolvedStyleValue } from '@expressive-code/core'; -import { h, select } from '@expressive-code/core/hast'; +import { type ExpressiveCodeLine, PluginStyleSettings, type UnresolvedStyleValue } from '@expressive-code/core'; +import { type Element, h, select } from '@expressive-code/core/hast'; import { uiTexts } from '../translations.ts'; import { type CodeblocksPlugin, insertAfter, insertBefore, lineElement } from './core.ts'; +import { isHiddenLine } from './hidden-lines.ts'; import { inlineMarkdown } from './inline-markdown.ts'; import { getRenderedDirectives } from './notation.ts'; -import { PREFIX, solidCodeBackground } from './styles.ts'; +import { markerColours, markerStyles, PREFIX } from './styles.ts'; export interface SkippedCodeStyleSettings { badgeBackground: UnresolvedStyleValue; @@ -17,23 +18,15 @@ declare module '@expressive-code/core' { } } -const styleSettings = new PluginStyleSettings({ - defaultValues: { - codeblocksSkippedCode: { - badgeBackground: (context) => - onBackground(setAlpha(context.resolveSetting('codeblocks.mutedForeground'), 0.1), solidCodeBackground(context)), - rule: ({ resolveSetting }) => setAlpha(resolveSetting('codeblocks.mutedForeground'), 0.35), - }, - }, -}); +const styleSettings = new PluginStyleSettings({ defaultValues: { codeblocksSkippedCode: markerColours } }); export interface SkippedCodeSettings { - /** Lines that stand for `[!code skip]`, alone or as the whole of a comment. */ + /** Lines that stand for `[!code skip]`, as the whole of a comment, or alone in JSON. None by default. */ aliases?: string[]; } /** Shows a marker where `[!code skip]` stands for code that the block leaves out. */ -export function pluginSkippedCode({ aliases = ['...'] }: SkippedCodeSettings = {}): CodeblocksPlugin { +export function pluginSkippedCode({ aliases = [] }: SkippedCodeSettings = {}): CodeblocksPlugin { return { name: 'starlight-codeblocks:skipped-code', directives: { @@ -51,34 +44,12 @@ export function pluginSkippedCode({ aliases = ['...'] }: SkippedCodeSettings = { }, styleSettings, baseStyles: ({ cssVar }) => ` -.${PREFIX}-skip-marker { - display: flex; - align-items: center; - position: relative; - margin: 2px 0; - padding-inline-start: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}); - color: ${cssVar('codeblocks.mutedForeground')}; - user-select: none; - -webkit-user-select: none; -} +${markerStyles(cssVar, `${PREFIX}-skip-marker`, `${PREFIX}-skip-text`, 'codeblocksSkippedCode', 'dotted')} +.${PREFIX}-skip-marker { padding-inline-start: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}); } /* An element, because a flex container drops text that is only whitespace. */ .${PREFIX}-skip-indent { white-space: pre; line-height: 0; } -.${PREFIX}-skip-marker::before { - content: ''; - position: absolute; - top: 50%; - inset-inline: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}) ${cssVar('codePaddingInline')}; - border-top: 1px dotted ${cssVar('codeblocksSkippedCode.rule')}; -} -.${PREFIX}-skip-text { - position: relative; - z-index: 1; - padding: 0.05em 0.65em; - border-radius: 999px; - background: ${cssVar('codeblocksSkippedCode.badgeBackground')}; - font-size: 0.8125em; - line-height: 1.6; -} +/* A marker between hidden lines shows with them. */ +.${PREFIX}-skip-hidden:not(.${PREFIX}-hidden-open) { display: none; } `, hooks: { postprocessRenderedBlock(context) { @@ -86,14 +57,25 @@ export function pluginSkippedCode({ aliases = ['...'] }: SkippedCodeSettings = { const code = directives.length > 0 && select('pre > code', context.renderData.blockAst); if (!code) return; const say = uiTexts(context.locale); + const { codeBlock } = context; + const all = codeBlock.getLines(); + const hiddenBefore = (line: ExpressiveCodeLine) => + isHiddenLine(codeBlock, line) && isHiddenLine(codeBlock, all[all.indexOf(line) - 1] as ExpressiveCodeLine); + // Markers after a line keep their source order. + const lastAfter = new Map(); for (const { lines, text, after, indent } of directives) { - const line = lines[0] && lineElement(lines[0]); - if (!line) continue; - const marker = h('div', { class: `${PREFIX}-skip-marker` }, [ + const line = lines[0]; + const el = line && lineElement(line); + if (!el) continue; + const hidden = !after && hiddenBefore(line); + const marker = h('div', { class: `${PREFIX}-skip-marker${hidden ? ` ${PREFIX}-skip-hidden` : ''}` }, [ ...(indent ? [h('span', { class: `${PREFIX}-skip-indent` }, indent)] : []), h('span', { class: `${PREFIX}-skip-text` }, text ? inlineMarkdown(text) : say('skippedCode.marker')), ]); - (after ? insertAfter : insertBefore)(code, line, marker); + if (after) { + insertAfter(code, lastAfter.get(el) ?? el, marker); + lastAfter.set(el, marker); + } else insertBefore(code, el, marker); } }, }, diff --git a/packages/starlight-codeblocks/src/expressive-code/styles.ts b/packages/starlight-codeblocks/src/expressive-code/styles.ts index fc8babd..b777bff 100644 --- a/packages/starlight-codeblocks/src/expressive-code/styles.ts +++ b/packages/starlight-codeblocks/src/expressive-code/styles.ts @@ -68,6 +68,55 @@ const tabBarBackground = ({ resolveSetting }: Context) => { } }; +/** Colours of a marker across the code, for the hidden lines and skipped code settings groups. */ +export const markerColours = { + badgeBackground: (context: Context) => + onBackground(setAlpha(context.resolveSetting('codeblocks.mutedForeground'), 0.1), solidCodeBackground(context)), + rule: ({ resolveSetting }: Context) => setAlpha(resolveSetting('codeblocks.mutedForeground'), 0.35), +}; + +/** + * A marker across the code, with a badge on a rule, as hidden lines and skipped code draw it. + * `group` holds the `markerColours` settings. + */ +export const markerStyles = ( + cssVar: ResolverContext['cssVar'], + marker: string, + badge: string, + group: 'codeblocksHiddenLines' | 'codeblocksSkippedCode', + border: 'dashed' | 'dotted', +) => ` +.${marker} { + display: flex; + align-items: center; + position: relative; + margin: 2px 0; + color: ${cssVar('codeblocks.mutedForeground')}; + user-select: none; + -webkit-user-select: none; +} +.${marker}::before { + content: ''; + position: absolute; + top: 50%; + inset-inline: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}) ${cssVar('codePaddingInline')}; + border-top: 1px ${border} ${cssVar(`${group}.rule` as never)}; + transform: translateY(-50%); +} +/* Where the copy button always shows, it sits over the end of the first line. */ +@media (hover: none) { + .${marker}:first-child::before { inset-inline-end: calc(${cssVar('codePaddingInline')} + 2.5rem); } +} +.${badge} { + position: relative; + z-index: 1; + padding: 0.05em 0.65em; + border-radius: 999px; + background: ${cssVar(`${group}.badgeBackground` as never)}; + font-size: 0.8125em; + line-height: 1.6; +}`; + /** `colour`, lightened or darkened to at least `min` contrast on the code background. */ export const onCode = (context: Context, colour: string, min: number) => ensureColorContrastOnBackground(colour, solidCodeBackground(context), min); diff --git a/packages/starlight-codeblocks/src/options.ts b/packages/starlight-codeblocks/src/options.ts index 8f3efa3..bc4d7c9 100644 --- a/packages/starlight-codeblocks/src/options.ts +++ b/packages/starlight-codeblocks/src/options.ts @@ -322,13 +322,13 @@ export const optionsReference: Record = { directives: true, description: 'Shows a marker in place of code that a block leaves out.', page: 'features/skipped-code', - off: '`[!code skip]` and `...` lines then stay in the code as written.', + off: '`[!code skip]` then stays in the code as written.', fields: { aliases: { type: 'string[]', - default: ['...'], + default: [], description: - 'Lines that stand for `[!code skip]`: a comment that holds only an alias, or the alias alone on its line in JSON, which has no comments. `[]` turns them off.', + "Lines that stand for `[!code skip]`: a comment that holds only an alias, such as `// ...`, or the alias alone on its line in JSON, which has no comments. `['...']` reads the `// ...` comments of existing pages as markers, which changes those pages: see the feature page.", valid: (value) => isStringArray(value) && (value as string[]).every((alias) => alias.trim() !== ''), }, }, diff --git a/packages/starlight-codeblocks/test/brackets.test.ts b/packages/starlight-codeblocks/test/brackets.test.ts index 5bbccf1..f7bc6c8 100644 --- a/packages/starlight-codeblocks/test/brackets.test.ts +++ b/packages/starlight-codeblocks/test/brackets.test.ts @@ -7,9 +7,9 @@ import { setRegistry } from '../src/registry.ts'; import { variants } from './contrast.ts'; import { block, render } from './render.ts'; -const js = commentSyntaxFor('js') ?? []; +const js = commentSyntaxFor('js'); const at = (lines: string[], lang: string) => - findBrackets(lines, commentSyntaxFor(lang) ?? []).map(({ line, column }) => [line, column]); + findBrackets(lines, commentSyntaxFor(lang)).map(({ line, column }) => [line, column]); test('findBrackets pairs brackets by nesting depth, and leaves out unmatched ones and ones in strings and comments', () => { const text = 'const a = (1 + [2, 3]);'; @@ -52,9 +52,7 @@ test('findBrackets counts brackets in template literal interpolations, also in a test('findBrackets reads quotes, comments and strings per language', () => { const rust = ['impl Foo {', " fn name<'a>(&'a self) -> &'static str {", " let c = '{';", ' }', '}']; - const closers = findBrackets(rust, commentSyntaxFor('rust') ?? [], true).filter( - (m) => rust[m.line]?.[m.column] === '}', - ); + const closers = findBrackets(rust, commentSyntaxFor('rust'), true).filter((m) => rust[m.line]?.[m.column] === '}'); expect(closers.map((m) => m.line)).toEqual([3, 4]); expect(findBrackets(["it's (fine)"], [])).toHaveLength(2); const python = ['result = run(', ' """', ' Steps: 1) load', " ''' [ '''", ' """,', ')']; @@ -65,7 +63,7 @@ test('findBrackets reads quotes, comments and strings per language', () => { [0, 9], [4, 0], ]); - const hash = findBrackets(['count() {', ` n=\${#items[@]} # (note)`, '}'], commentSyntaxFor('bash') ?? []); + const hash = findBrackets(['count() {', ` n=\${#items[@]} # (note)`, '}'], commentSyntaxFor('bash')); expect(hash).toHaveLength(8); expect(hash.at(-1)).toMatchObject({ line: 2, column: 0, depth: 0 }); }); diff --git a/packages/starlight-codeblocks/test/notation.test.ts b/packages/starlight-codeblocks/test/notation.test.ts index 8d6d827..a17659f 100644 --- a/packages/starlight-codeblocks/test/notation.test.ts +++ b/packages/starlight-codeblocks/test/notation.test.ts @@ -1,5 +1,5 @@ import { describe, expect, test } from 'vitest'; -import { commentSyntaxFor } from '../src/expressive-code/comments.ts'; +import { commentSyntaxFor, hasNoComments } from '../src/expressive-code/comments.ts'; import { type DirectiveSpecs, parseLine, parseNotation } from '../src/expressive-code/notation.ts'; const specs: DirectiveSpecs = { @@ -12,7 +12,7 @@ const specs: DirectiveSpecs = { link: {}, 'code skip': { text: true, endOfBlock: true, aliases: ['...'] }, }; -const js = commentSyntaxFor('js') ?? []; +const js = commentSyntaxFor('js'); function parse(text: string, syntaxes = js) { const problems: string[] = []; @@ -45,7 +45,7 @@ describe('parseLine', () => { ['lisp', "(setq x 'foo) ; it's [!code focus]", "(setq x 'foo) ; it's"], ['md', "Don't ", "Don't "], ])('%s: reads and removes the directive in %j', (lang, input, text) => { - const result = parse(input, commentSyntaxFor(lang) ?? []); + const result = parse(input, commentSyntaxFor(lang)); expect(result).toMatchObject({ text, removed: false, problems: [] }); expect(result.directives).toHaveLength(1); }); @@ -86,8 +86,8 @@ describe('parseLine', () => { test('removes lines that hold only directives', () => { expect(parse(' // [!callout /a/] Note')).toMatchObject({ removed: true, text: '' }); - expect(parse(' /* [!code focus] */', commentSyntaxFor('css') ?? [])).toMatchObject({ text: '', removed: true }); - const jsx = parse(' {/* [!callout] Note */}', commentSyntaxFor('tsx') ?? []); + expect(parse(' /* [!code focus] */', commentSyntaxFor('css'))).toMatchObject({ text: '', removed: true }); + const jsx = parse(' {/* [!callout] Note */}', commentSyntaxFor('tsx')); expect(jsx).toMatchObject({ removed: true, directives: [{ text: 'Note' }] }); }); @@ -108,7 +108,7 @@ describe('parseLine', () => { directives: [{ name: 'callout', text: 'Why' }], problems: [], }); - expect(parse('# fixes #12 [!callout /x/] Why', commentSyntaxFor('py') ?? [])).toMatchObject({ + expect(parse('# fixes #12 [!callout /x/] Why', commentSyntaxFor('py'))).toMatchObject({ removed: false, text: '# fixes #12', }); @@ -168,8 +168,8 @@ describe('parseNotation', () => { test('reads a line that holds only an alias, in a comment or in a language with no comments', () => { const skip = (lines: string[], lang = 'js', comments = {}) => - parseNotation(lines, commentSyntaxFor(lang, comments), specs, () => {}).map(({ removed, directives }) => - removed ? 'removed' : directives.map((d) => d.name).join(), + parseNotation(lines, commentSyntaxFor(lang, comments), specs, () => {}, false, hasNoComments(lang, comments)).map( + ({ removed, directives }) => (removed ? 'removed' : directives.map((d) => d.name).join()), ); expect(skip(['a()', ' // ...', 'b()'])).toEqual(['', 'removed', 'code skip']); expect(skip(['a()', '/* ... */'])).toEqual(['code skip', 'removed']); @@ -183,7 +183,10 @@ describe('parseNotation', () => { test('commentSyntaxFor uses the built-in map, Shiki aliases and the options', () => { expect(commentSyntaxFor('Python')).toEqual([{ open: '#', close: undefined }]); expect(commentSyntaxFor('css')).toEqual([{ open: '/*', close: '*/' }]); - expect(commentSyntaxFor('json')).toBeUndefined(); + expect(commentSyntaxFor('json')).toEqual([]); + expect(hasNoComments('json')).toBe(true); + expect(hasNoComments('json', { json: ['//'] })).toBe(false); + expect(hasNoComments('fsharp')).toBe(false); expect(commentSyntaxFor('pwsh')).toEqual(commentSyntaxFor('powershell')); expect(commentSyntaxFor('shellsession')).toEqual([{ open: '#', close: undefined }]); expect(commentSyntaxFor('pwsh', { powershell: ['//'] })).toEqual([{ open: '//', close: undefined }]); diff --git a/packages/starlight-codeblocks/test/options.test.ts b/packages/starlight-codeblocks/test/options.test.ts index 8e37c61..03a01ec 100644 --- a/packages/starlight-codeblocks/test/options.test.ts +++ b/packages/starlight-codeblocks/test/options.test.ts @@ -14,7 +14,7 @@ test('turns every feature on with defaults, in new objects on each call', () => expect(options.footnotes).toEqual({ sticky: false, style: 'outline' }); expect(options.shellCopy).toEqual({ prompts: ['$ ', '> '] }); expect(options.expandable).toEqual({ lines: 12, auto: false }); - expect(options.skippedCode).toEqual({ aliases: ['...'] }); + expect(options.skippedCode).toEqual({ aliases: [] }); expect(options.inlineHighlighting).toEqual({ defaultLanguage: false }); expect(options.playgrounds).toEqual({}); expect(options.walkthrough).toEqual({ start: 1 }); diff --git a/packages/starlight-codeblocks/test/skipped-code.test.ts b/packages/starlight-codeblocks/test/skipped-code.test.ts index b3c9c34..eab2e74 100644 --- a/packages/starlight-codeblocks/test/skipped-code.test.ts +++ b/packages/starlight-codeblocks/test/skipped-code.test.ts @@ -1,7 +1,8 @@ import { expect, test } from 'vitest'; import { block, render } from './render.ts'; -const marker = (html: string) => html.match(/
.*?<\/div>/g) ?? []; +const marker = (html: string) => html.match(/
.*?<\/div>/g) ?? []; +const dots = { skippedCode: { aliases: ['...'] } }; test('puts a marker where a [!code skip] line was, and leaves it out of the copied text', async () => { const { html, copyText, warnings } = await render( @@ -35,11 +36,43 @@ test('puts a marker above a line with a trailing [!code skip]', async () => { expect(html).toMatch(/>a<.*scb-skip-marker.*>b { - const js = await render(block('js', 'function connect() {', ' // ...', ' return socket;', '}')); +test('puts markers at the end of a block in source order', async () => { + const { html } = await render(block('js', 'a();', '// [!code skip] One', '// [!code skip] Two')); + expect(html).toMatch(/One.*Two/); +}); + +test('hides a marker between hidden lines with them, but not one above a run', async () => { + const { html } = await render(block('js hidden={2-4}', 'a();', 'b();', '// [!code skip] Inside', 'c();', 'd();')); + expect(marker(html)).toEqual([expect.stringContaining('scb-skip-marker scb-skip-hidden">')]); + const above = await render(block('js hidden={2-3}', 'a();', '// [!code skip] Above', 'b();', 'c();')); + expect(marker(above.html)).toEqual([expect.stringContaining('class="scb-skip-marker">')]); +}); + +test('reads a directive line with a diff prefix, at the indentation that readers see', async () => { + const { html, copyText } = await render( + block('diff lang="js"', ' function f() {', '+ // ...', '+ return 1;', ' }'), + dots, + ); + expect(marker(html)).toEqual([expect.stringContaining(' ')]); + expect(copyText).toBe('function f() {\n return 1;\n}'); +}); + +test('puts a marker at the end of a block after the last line of code, not after output lines', async () => { + const { html, warnings } = await render(block('sh', 'make', '# [!output]', 'built', '# [!code skip]')); + expect(warnings).toEqual([]); + expect(html).toMatch(/make.*scb-skip-marker/); +}); + +test('leaves `...` lines as written by default, so ranges keep their lines', async () => { + const md = block('js {3}', 'a();', '// ...', 'b();'); + expect((await render(md)).html).toBe((await render(md, { skippedCode: false })).html); +}); + +test('reads `...` alone in a comment, or alone on its line in a language with no comments, with the alias', async () => { + const js = await render(block('js', 'function connect() {', ' // ...', ' return socket;', '}'), dots); 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,', ' ...', '}')); + const json = await render(block('json', '{', ' "a": 1,', ' ...', '}'), dots); expect(marker(json.html)).toHaveLength(1); expect(json.copyText).toBe('{\n "a": 1,\n}'); expect(json.warnings).toEqual([]); @@ -53,14 +86,14 @@ test('leaves `...` that is code, or that has more text, as written', async () => block('json', '[', ' "..."', ']'), block('fsharp', 'let f () =', ' ...'), ]) { - expect(marker((await render(md)).html)).toEqual([]); + expect(marker((await render(md, dots)).html)).toEqual([]); } }); -test('takes custom aliases, and none with `aliases: []`', async () => { +test('takes custom aliases, and none by default', async () => { const md = block('js', 'a();', '// …', '// [...]', 'b();'); expect(marker((await render(md, { skippedCode: { aliases: ['…', '[...]'] } })).html)).toHaveLength(2); - const { html, copyText } = await render(block('js', 'a();', '// ...', 'b();'), { skippedCode: { aliases: [] } }); + const { html, copyText } = await render(block('js', 'a();', '// ...', 'b();')); expect(marker(html)).toEqual([]); expect(copyText).toBe('a();\n// ...\nb();'); }); diff --git a/skills/starlight-codeblocks/SKILL.md b/skills/starlight-codeblocks/SKILL.md index 6c51335..39506a5 100644 --- a/skills/starlight-codeblocks/SKILL.md +++ b/skills/starlight-codeblocks/SKILL.md @@ -77,7 +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 keep `// ...` | A marker takes the place of the code. The copied code is incomplete. | +| Code that the example leaves out, where authors write `// ...` | Skipped code: `[!code skip]`, or `// ...` with `skippedCode.aliases` | A marker takes the place of the code. 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. | @@ -166,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, if the site sets `skippedCode.aliases: ['...']`. It also reads `...` alone on its line in JSON. Those lines leave the code and the copied code, so line ranges after them, such as `{4}` or `ins={4}`, count different lines. Check the ranges of each block with `// ...` when the site turns this on. 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. diff --git a/skills/starlight-codeblocks/references/configuration.md b/skills/starlight-codeblocks/references/configuration.md index 61fd05d..4c72fff 100644 --- a/skills/starlight-codeblocks/references/configuration.md +++ b/skills/starlight-codeblocks/references/configuration.md @@ -32,7 +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` | `aliases`: lines that are the same as `[!code skip]`, default `['...']` | Skipped code | +| `skippedCode` | `aliases`: comments, and JSON lines, that are the same as `[!code skip]`, default `[]`. `['...']` reads `// ...` as a marker and changes existing pages | 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..637fd74 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, a hidden lines marker or a skipped code 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 dfbe6d5..9b8927e 100644 --- a/skills/starlight-codeblocks/references/readability.md +++ b/skills/starlight-codeblocks/references/readability.md @@ -49,8 +49,8 @@ Use where an example shows part of a file and leaves code out. A marker takes th |---|---| | `[!code skip]` | Comment on its own line where the code is left out, or at the end of the line below that place | | `[!code skip] text` | The same, with `text` on the marker in place of "Code not shown" | -| `// ...` | Comment that holds only `...`, on its own line, in the comment syntax of the language (`# ...`) | -| `...` | On its own line, in JSON | +| `// ...` | Comment that holds only `...`, on its own line, in the comment syntax of the language (`# ...`). Only with `skippedCode.aliases: ['...']` | +| `...` | On its own line, in JSON. Only with `skippedCode.aliases: ['...']` | ```js app.get('/users', async (req, res) => { @@ -63,9 +63,11 @@ app.get('/users', async (req, res) => { - A directive line at the end of the block puts the marker after the last line. - The copied code has no marker, and no skipped code. Do not use it in a block with a playground or the **Run code** button. - Line numbers do not jump over the marker. -- A comment with other text, such as `// ... more`, stays in the code. For a marker with text, use `[!code skip] text`. -- `...` alone on its line is a marker only in JSON. In Python and YAML, it stays as code. -- Option: `skippedCode.aliases` (default `['...']`) sets the lines that are the same as `[!code skip]`. `[]` turns them off. `skippedCode: false` leaves `[!code skip]` and `...` in the code. +- Option: `skippedCode.aliases` (default `[]`) sets the lines that are the same as `[!code skip]`. By default, `// ...` stays in the code as written. `['...']` reads a comment that holds only `...` as a marker, and `...` alone on its line in JSON. In Python and YAML, a bare `...` stays as code. +- The aliases change existing pages: the `// ...` lines leave the code, so line ranges after them, such as `{4}` or `ins={4}`, count different lines. Check those blocks when you set the option. +- With the aliases, 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`. +- A code walkthrough or scrollycoding step with a marker changes without the animation. +- `skippedCode: false` leaves `[!code skip]` in the code. ## Expandable blocks From 3746954a818299ec9dbfa46652c78881f11103fd Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 19:22:34 +0100 Subject: [PATCH 07/11] docs: say that an empty comment list turns off skipped code aliases only when a site uses them Co-Authored-By: Claude Opus 5.5 --- docs/src/content/docs/comment-notation.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/comment-notation.mdx b/docs/src/content/docs/comment-notation.mdx index c2e55cb..3612e8e 100644 --- a/docs/src/content/docs/comment-notation.mdx +++ b/docs/src/content/docs/comment-notation.mdx @@ -283,7 +283,9 @@ codeblocks({ }); ``` -An entry replaces the built-in syntax of that language. A language name or its alias works: an entry for `powershell` also applies to ` ```pwsh `. An empty list, such as `md: []`, turns off directives for that language, including the `...` lines of [skipped code](/starlight-codeblocks/features/skipped-code/). The built-in map: +An entry replaces the built-in syntax of that language. A language name or its alias works: an entry for `powershell` also applies to ` ```pwsh `. + +An empty list, such as `md: []`, turns off directives for that language. When a site reads `...` lines as [skipped code](/starlight-codeblocks/features/skipped-code/), it turns them off too. The built-in map: From 0200c7a850d81e93e352c7f48a65f99cfb0e15b2 Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 19:30:06 +0100 Subject: [PATCH 08/11] docs: move skipped code aliases out of the syntax table into their own section Co-Authored-By: Claude Opus 5.5 --- .../content/docs/features/skipped-code.mdx | 97 ++++++++++--------- .../references/readability.md | 4 +- 2 files changed, 50 insertions(+), 51 deletions(-) diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx index f97fa20..2528af3 100644 --- a/docs/src/content/docs/features/skipped-code.mdx +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -7,7 +7,7 @@ import { LinkCard } from '@astrojs/starlight/components'; import Example from '../../../components/Example.astro'; import Options from '../../../components/Options.astro'; -An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. Skipped code puts a marker in its place, which looks different from the code and is not part of the copied text. Write the `[!code skip]` directive, with optional text. A site can also [read its `// ...` comments as markers](#read---as-markers). +An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. Skipped code puts a marker in its place, which looks different from the code and is not part of the copied text. Write the `[!code skip]` directive, with optional text. A site can also read its `// ...` comments as markers, with [aliases](#aliases). export const basic = ` \`\`\`js title="routes.js" @@ -35,37 +35,29 @@ The first marker replaces the body of the `get` handler and shows the text after |---|---| | `[!code skip]` | Comment on its own line, or at the end of a line | | `[!code skip] text` | Comment on its own line, or at the end of a line | -| `// ...` | Comment that holds only `...`, on its own line, with `aliases: ['...']`. Use the comment syntax of the language, such as `# ...` | -| `...` | On its own line, in JSON, with `aliases: ['...']` | Put the directive on its own line where the code is left out. The marker takes the place of that line, with the same indentation. At the end of a line, the marker goes above that line. Without text, the marker reads "Code not shown". The text can hold inline code, links and bold text. -## Examples - -### Skip code without text +:::tip +Does your site already use `// ...` comments for code that is left out? Set [aliases](#aliases) to show them as markers, without rewriting them as directives. Aliases are off by default, because they change the line ranges of existing blocks. +::: -Without text, the marker reads "Code not shown". Use it when the code around the marker tells readers what is left out: +## Aliases -export const noText = ` -\`\`\`ts title="cache.ts" -export class Cache { - private entries = new Map(); +Many pages already use `// ...` for code that they leave out. By default, these comments stay in the code as written. To read them as markers, set `skippedCode.aliases`: - // [!code skip] - - get(key: string): T | undefined { - return this.entries.get(key); - } - // [!code skip] -} -\`\`\` -`; +```js title="astro.config.mjs" +codeblocks({ + skippedCode: { aliases: ['...'] }, +}); +``` - +A line is then the same as `[!code skip]` if it holds one of these, and nothing else: -### Skip code in JSON +- A comment with only `...` in it, in the comment syntax of the language: `// ...`, `# ...`, `/* ... */` or ``. +- `...` with no comment, in JSON. JSON has no comments, so the directive cannot go in a JSON block. -JSON has no comments, so the directive cannot go in a JSON block. With the `...` alias, `...` on its own line is the marker. This site sets the alias: +Add more aliases to the list, such as `'…'`. An alias takes no text: for a marker with text, write `[!code skip] text`. This site sets `['...']`, so this JSON block shows two markers: export const json = ` \`\`\`json title="package.json" @@ -82,7 +74,40 @@ export const json = ` -`...` alone on its line is a marker only in JSON. In Python, `...` is code, and in YAML it ends a document, so these blocks keep it. Without the alias, use `jsonc`, which has comments. +In Python, `...` is code, and in YAML it ends a document, so a `...` with no comment stays in these blocks. + +:::caution +Aliases change existing pages. Check the pages that use `// ...` after you set them: + +- The `// ...` lines leave the code, so line ranges count different lines. In a block with `// ...` on line 2, `{4}` marks the line that was line 5. This applies to every range attribute, such as `ins={4}` and `focus={4}`. +- The `// ...` lines also leave the copied code. +- A [code walkthrough](/starlight-codeblocks/features/code-walkthrough/) or [scrollycoding](/starlight-codeblocks/features/scrollycoding/) step with a marker changes without the animation. +::: + +To keep `// ...` as code in one block, add text to the comment, such as `// ... and so on`. A comment with more than an alias in it stays in the code. A language with `[]` in `notation.comments` reads no directives and no aliases. + +## Examples + +### Skip code without text + +Without text, the marker reads "Code not shown". Use it when the code around the marker tells readers what is left out: + +export const noText = ` +\`\`\`ts title="cache.ts" +export class Cache { + private entries = new Map(); + + // [!code skip] + + get(key: string): T | undefined { + return this.entries.get(key); + } + // [!code skip] +} +\`\`\` +`; + + ### Skip the start of a file @@ -138,30 +163,6 @@ volumes: -### Read `// ...` as markers - -Many pages already use `// ...` for code that they leave out. By default, these comments stay in the code as written. To read them as markers, set `aliases`: - -```js title="astro.config.mjs" -codeblocks({ - skippedCode: { aliases: ['...'] }, -}); -``` - -A comment with only an alias in it is then the same as `[!code skip]`, such as `// ...`, `# ...` or `/* ... */`. It must be alone on its line. In JSON, `...` alone on its line is a marker. Add more aliases to the list, such as `'…'`. - -:::caution -The aliases change existing pages. Check the pages that use `// ...` after you set them: - -- The `// ...` lines leave the code, so line ranges count different lines. In a block with `// ...` on line 2, `{4}` marks the line that was line 5. This applies to every range attribute, such as `ins={4}` and `focus={4}`. -- The `// ...` lines also leave the copied code. -- A [code walkthrough](/starlight-codeblocks/features/code-walkthrough/) or [scrollycoding](/starlight-codeblocks/features/scrollycoding/) step with a marker changes without the animation. -::: - -To keep `// ...` as code in one block, add text to the comment, such as `// ... and so on`. A comment with text other than an alias stays in the code. A language with `[]` in `notation.comments` reads no directives and no aliases. - -### Turn the feature off - Turn the feature off for the whole site with `skippedCode: false`. The plugin then does not know the `[!code skip]` directive. It leaves the directive in the code as written, and logs a build warning. diff --git a/skills/starlight-codeblocks/references/readability.md b/skills/starlight-codeblocks/references/readability.md index 9b8927e..de8089d 100644 --- a/skills/starlight-codeblocks/references/readability.md +++ b/skills/starlight-codeblocks/references/readability.md @@ -49,8 +49,6 @@ Use where an example shows part of a file and leaves code out. A marker takes th |---|---| | `[!code skip]` | Comment on its own line where the code is left out, or at the end of the line below that place | | `[!code skip] text` | The same, with `text` on the marker in place of "Code not shown" | -| `// ...` | Comment that holds only `...`, on its own line, in the comment syntax of the language (`# ...`). Only with `skippedCode.aliases: ['...']` | -| `...` | On its own line, in JSON. Only with `skippedCode.aliases: ['...']` | ```js app.get('/users', async (req, res) => { @@ -63,7 +61,7 @@ app.get('/users', async (req, res) => { - A directive line at the end of the block puts the marker after the last line. - The copied code has no marker, and no skipped code. Do not use it in a block with a playground or the **Run code** button. - Line numbers do not jump over the marker. -- Option: `skippedCode.aliases` (default `[]`) sets the lines that are the same as `[!code skip]`. By default, `// ...` stays in the code as written. `['...']` reads a comment that holds only `...` as a marker, and `...` alone on its line in JSON. In Python and YAML, a bare `...` stays as code. +- Aliases: `skippedCode.aliases` (default `[]`) sets the lines that are the same as `[!code skip]`. By default, `// ...` stays in the code as written. `['...']` reads a line that holds only a comment with only `...` in it (`// ...`, `# ...`) as a marker. In JSON, which has no comments, it reads `...` alone on its line. In Python and YAML, a bare `...` stays as code. - The aliases change existing pages: the `// ...` lines leave the code, so line ranges after them, such as `{4}` or `ins={4}`, count different lines. Check those blocks when you set the option. - With the aliases, 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`. - A code walkthrough or scrollycoding step with a marker changes without the animation. From e81449aa4cedba5a105766f94f2589067a579701 Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Wed, 18 Nov 2026 08:18:15 +0100 Subject: [PATCH 09/11] skipped-code: keep the skip line in the block, and set aliases per language A `[!code skip]` line now stays a line of the block: it keeps its line number, ranges count it, and it copies as a plain comment (`// text`, or `// ...`). The comment stays in the line, clipped and `aria-hidden`, and the badge is drawn after the indentation. This removes the special cases for markers at the end of a block, in hidden runs, after output and in print. The directive warns with a count or on a line with code. `skippedCode.aliases` becomes `commentAliases` and `bareAliases`, maps by language with `*` for the rest, merged over the defaults `{ '*': ['...'] }` and `{ json: ['...'] }`. Also caches the merged directive specs per site, uses one diff prefix rule, and types the marker style settings without casts. Co-Authored-By: Claude Opus 5.5 --- .agents/DECISIONS.md | 2 +- docs/astro.config.mjs | 1 - docs/e2e/skipped-code.test.ts | 27 ++-- docs/src/content/docs/comment-notation.mdx | 2 +- .../docs/features/code-walkthrough.mdx | 2 +- .../content/docs/features/skipped-code.mdx | 67 ++++---- .../src/client/hidden-lines.ts | 6 +- .../src/expressive-code/comments.ts | 18 +-- .../src/expressive-code/notation.ts | 150 ++++++++++-------- .../src/expressive-code/skipped-code.ts | 79 ++++----- .../src/expressive-code/styles.ts | 4 +- packages/starlight-codeblocks/src/options.ts | 22 ++- .../test/notation.test.ts | 57 ++++--- .../starlight-codeblocks/test/options.test.ts | 6 +- .../test/skipped-code.test.ts | 128 ++++++++------- skills/starlight-codeblocks/SKILL.md | 4 +- .../references/configuration.md | 2 +- .../references/explain-code.md | 2 +- .../references/readability.md | 18 +-- 19 files changed, 328 insertions(+), 269 deletions(-) diff --git a/.agents/DECISIONS.md b/.agents/DECISIONS.md index eff7743..f6101b4 100644 --- a/.agents/DECISIONS.md +++ b/.agents/DECISIONS.md @@ -96,7 +96,7 @@ The choices that the code does not explain, with the options that were rejected. - **Expandable blocks collapse only in the client**, with `hidden="until-found"`, so a block is complete without JavaScript and find in page reveals lines. Collapsed lines use `content-visibility: hidden` because EC's `all: revert` removes the browser's until-found style. `auto` skips code tabs variants, runnable blocks and collapsible sections; the components remove an `auto` cap. - **The hidden-lines toggle label changes, with no `aria-pressed`**, which would contradict the label. Open hidden lines dim to 0.75 opacity by the user's choice; syntax colours stay at 3:1 or more, and the accessibility page lists it as an exception with `openOpacity: '1'` to turn it off. - **A manual selection leaves out closed hidden lines.** The copy button includes them. *Rejected:* a `copy` handler that adds them (the paste would differ from the selection). -- **Skipped code is the `[!code skip]` directive and its aliases**, written where an author would write `// ...`. The marker is static HTML with no client module, and not a button, as there is nothing to open. It takes the indentation of the directive line, and a directive line at the end of the block puts it after the last line (`endOfBlock` on the directive spec). The badge text says what the marker is, so the dotted rule is decoration and stays as faint as the dashed hidden lines rule. A line that holds only an alias (`skippedCode.aliases`) is the same directive: as a whole comment (`// ...`), or alone in JSON, so that `...` in Python or YAML stays code. Aliases are off by default: `// ...` lines leave the code, which moves every range after them and stops walkthrough animations, on pages that never asked for the feature. With aliases on, a comment with more text (`// ... and so on`) keeps a `// ...` as code; no per-block switch. Only JSON: a language with no entry in the comment table may still have comments (F#, Elixir). Aliases take no text, so a comment such as `// ... more` stays as written. `[]` in `notation.comments` reads nothing, aliases too, so the docs' `md` source panes keep `...`. *Rejected:* a `skip={range}` attribute (a range names lines, not the gaps between them, and cannot name the end); `:N` as a count of skipped lines that makes line numbers jump (other directives read `:N` as the lines they apply to). +- **Skipped code restyles a `// ...` line; it is not a marker between lines.** `[!code skip]` and its aliases stay a line of the block, by the user's choice, as the `// ...` comments they replace were: the line keeps its number, ranges count it, and it copies as a plain comment (`// text`, or `// ...` without text; an alias line as written). The comment stays in the line, selectable and `aria-hidden`, clipped like screen reader text (Chromium leaves zero-width text and flex items out of a selection); the badge after the indentation is the decoration, so screen readers read the badge and copy matches the line. The directive takes no `:N` and does nothing on a line with code, because it stands for a line of its own. Aliases are `commentAliases` (a comment that holds only the alias) and `bareAliases` (the alias alone on its line), each a map by language with `*` for the rest, so a site can read a bare `...` in YAML without reading it everywhere. A language entry replaces `*`, so `[]` opts a language out, and the site's keys merge over the defaults, so adding YAML keeps JSON. Defaults are `{ '*': ['...'] }` and `{ json: ['...'] }`, as an alias only changes how a line looks. The examples are for reading, not running, so the docs do not warn about bare aliases in languages where `...` is code. Aliases take no text, so `// ... more` stays as written. A language with `[]` in `notation.comments` has no comment syntax, so it reads no comment aliases, which keeps `...` in the docs' `md` source panes. *Rejected:* aliases off by default (existing `// ...` lines are what the feature is for); one `aliases` list with bare aliases only in JSON; a marker between lines with no line number (ranges after it moved, and it needed special cases at the end of a block, in hidden runs, in output and in print); copying nothing for the line; a `skip={range}` attribute (a range names lines, not the gaps between them); `:N` as a count of skipped lines that makes line numbers jump. ### Copy, run, playgrounds, placeholders diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 0afb577..f678ec6 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -38,7 +38,6 @@ export default defineConfig({ codeblocks({ // Markdown blocks on this site show the source that authors write, so their directives must stay as text. notation: { comments: { md: [], markdown: [], mdx: [] } }, - skippedCode: { aliases: ['...'] }, shellCopy: { prompts: ['$ ', '> ', 'PS> '] }, swatches: { prose: true }, fileIcons: { diff --git a/docs/e2e/skipped-code.test.ts b/docs/e2e/skipped-code.test.ts index b3539ed..ceeeb1a 100644 --- a/docs/e2e/skipped-code.test.ts +++ b/docs/e2e/skipped-code.test.ts @@ -36,14 +36,23 @@ test('a marker starts at the indentation of its directive line, and every marker expect(Math.abs((result.heights[0] ?? 0) - (result.heights[1] ?? 0))).toBeLessThan(1); }); -test('a manual selection leaves out the marker text', async ({ page }) => { - const text = await example(page) - .locator('pre code') - .evaluate((code) => { - getSelection()?.selectAllChildren(code); - return getSelection()?.toString(); +test('a manual selection copies each marker as its comment, as the copy button does', async ({ page }) => { + const { selected, copied } = await example(page) + .locator('figure') + .evaluate((figure) => { + getSelection()?.selectAllChildren(figure.querySelector('pre code') as Node); + return { + selected: getSelection()?.toString(), + copied: figure.querySelector('button[data-code]')?.getAttribute('data-code')?.replaceAll('\x7F', '\n'), + }; }); - expect(text).not.toContain('Read the users'); - expect(text).not.toContain('Code not shown'); - expect(text).toContain('res.status(201).json(user);'); + expect(selected).toContain(' // Not shown: Read the users from the database\n'); + expect(selected).not.toContain('Code not shown'); + expect(selected?.trimEnd()).toBe(copied?.trimEnd()); +}); + +test('a marker line hides its comment and shows its text', async ({ page }) => { + const line = example(page).locator('.scb-skip-line').first(); + await expect(line.locator('.scb-skip-source')).toHaveCSS('clip-path', 'inset(50%)'); + await expect(line.locator('.scb-skip-text')).toBeVisible(); }); diff --git a/docs/src/content/docs/comment-notation.mdx b/docs/src/content/docs/comment-notation.mdx index 3612e8e..86dafa4 100644 --- a/docs/src/content/docs/comment-notation.mdx +++ b/docs/src/content/docs/comment-notation.mdx @@ -285,7 +285,7 @@ codeblocks({ An entry replaces the built-in syntax of that language. A language name or its alias works: an entry for `powershell` also applies to ` ```pwsh `. -An empty list, such as `md: []`, turns off directives for that language. When a site reads `...` lines as [skipped code](/starlight-codeblocks/features/skipped-code/), it turns them off too. The built-in map: +An empty list, such as `md: []`, turns off directives for that language, and the comment aliases of [skipped code](/starlight-codeblocks/features/skipped-code/). The built-in map: diff --git a/docs/src/content/docs/features/code-walkthrough.mdx b/docs/src/content/docs/features/code-walkthrough.mdx index c24c7a3..c5f4fcc 100644 --- a/docs/src/content/docs/features/code-walkthrough.mdx +++ b/docs/src/content/docs/features/code-walkthrough.mdx @@ -247,7 +247,7 @@ def greet(name, greeting="Hello"): - 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. - A step with removed or added lines changes without the animation, so its diff colours and `+` and `-` markers stay in place. - - A step with a callout, a hidden lines marker or a skipped code marker changes without the animation. The animation does not have the height of these rows. + - A step with a callout or a hidden lines marker changes without the animation. The animation does not have the height of these rows. ## Options diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx index 2528af3..d658131 100644 --- a/docs/src/content/docs/features/skipped-code.mdx +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -7,7 +7,7 @@ import { LinkCard } from '@astrojs/starlight/components'; import Example from '../../../components/Example.astro'; import Options from '../../../components/Options.astro'; -An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. Skipped code puts a marker in its place, which looks different from the code and is not part of the copied text. Write the `[!code skip]` directive, with optional text. A site can also read its `// ...` comments as markers, with [aliases](#aliases). +An example often shows only part of a file. Authors then write a comment such as `// ...` where code is left out, and readers can mistake it for code. Skipped code draws that line as a marker, which looks different from the code. The line keeps its line number, and copies as a plain comment. Write the `[!code skip]` directive, with optional text. Existing `// ...` comments also show as markers, through [aliases](#aliases). export const basic = ` \`\`\`js title="routes.js" @@ -27,37 +27,25 @@ app.post('/users', async (req, res) => { -The first marker replaces the body of the `get` handler and shows the text after the directive. The second marker shows that the file goes on after the last line. Copying the block gives the code without the markers. +The first marker replaces the body of the `get` handler and shows the text after the directive. The second marker shows that the file goes on after the last line. Copying the block gives each marker as a comment, such as `// Not shown: Read the users from the database`. ## Syntax | Syntax | Where | |---|---| -| `[!code skip]` | Comment on its own line, or at the end of a line | -| `[!code skip] text` | Comment on its own line, or at the end of a line | +| `[!code skip]` | Comment on its own line | +| `[!code skip] text` | Comment on its own line | -Put the directive on its own line where the code is left out. The marker takes the place of that line, with the same indentation. At the end of a line, the marker goes above that line. Without text, the marker reads "Code not shown". The text can hold inline code, links and bold text. - -:::tip -Does your site already use `// ...` comments for code that is left out? Set [aliases](#aliases) to show them as markers, without rewriting them as directives. Aliases are off by default, because they change the line ranges of existing blocks. -::: +Put the directive on its own line where the code is left out. That line shows as the marker, at the same indentation. Without text, the marker reads "Code not shown". The text can hold inline code, links and bold text. ## Aliases -Many pages already use `// ...` for code that they leave out. By default, these comments stay in the code as written. To read them as markers, set `skippedCode.aliases`: - -```js title="astro.config.mjs" -codeblocks({ - skippedCode: { aliases: ['...'] }, -}); -``` - -A line is then the same as `[!code skip]` if it holds one of these, and nothing else: +Many pages already use `// ...` for code that they leave out. These lines are the same as `[!code skip]` by default, so existing pages show markers with no changes. A line is an alias if it holds one of these, and nothing else: -- A comment with only `...` in it, in the comment syntax of the language: `// ...`, `# ...`, `/* ... */` or ``. -- `...` with no comment, in JSON. JSON has no comments, so the directive cannot go in a JSON block. +- A comment alias: a comment with only the alias in it, in the comment syntax of the language, such as `// ...`, `# ...`, `/* ... */` or ``. By default, `...` in every language. +- A bare alias: the alias with no comment. By default, `...` in JSON, which has no comments, so the directive cannot go in a JSON block. -Add more aliases to the list, such as `'…'`. An alias takes no text: for a marker with text, write `[!code skip] text`. This site sets `['...']`, so this JSON block shows two markers: +This JSON block shows two markers: export const json = ` \`\`\`json title="package.json" @@ -74,17 +62,22 @@ export const json = ` -In Python, `...` is code, and in YAML it ends a document, so a `...` with no comment stays in these blocks. +An alias changes only how the line looks. The line keeps its line number, line ranges count it, and the copied code has the `// ...` as written. An alias takes no text: for a marker with text, write `[!code skip] text`. -:::caution -Aliases change existing pages. Check the pages that use `// ...` after you set them: +Set `skippedCode.commentAliases` and `skippedCode.bareAliases` to change the aliases. Each is a list of aliases for each language, and `*` applies to every language without its own entry. Your entries merge over the defaults, and `[]` turns aliases off for a language: -- The `// ...` lines leave the code, so line ranges count different lines. In a block with `// ...` on line 2, `{4}` marks the line that was line 5. This applies to every range attribute, such as `ins={4}` and `focus={4}`. -- The `// ...` lines also leave the copied code. -- A [code walkthrough](/starlight-codeblocks/features/code-walkthrough/) or [scrollycoding](/starlight-codeblocks/features/scrollycoding/) step with a marker changes without the animation. -::: +```js title="astro.config.mjs" +codeblocks({ + skippedCode: { + // `// …` too, in every language, and no comment aliases in Python + commentAliases: { '*': ['...', '…'], python: [] }, + // `...` with no comment in YAML, as well as in JSON + bareAliases: { yaml: ['...'] }, + }, +}); +``` -To keep `// ...` as code in one block, add text to the comment, such as `// ... and so on`. A comment with more than an alias in it stays in the code. A language with `[]` in `notation.comments` reads no directives and no aliases. +A language name or its alias works as a key: `yaml` also applies to ` ```yml `. To keep `// ...` as code in one block, add text to the comment, such as `// ... and so on`. A language with `[]` in `notation.comments` has no comment syntax, so it reads no comment aliases. ## Examples @@ -148,14 +141,15 @@ volumes: ## Behaviour - The marker: - - A dotted rule across the block, with the text in a badge at the indentation of the directive line. + - A dotted rule across the line, with the text in a badge at the indentation of the directive line. - The marker is not a button. Readers cannot open it, because the code is not in the block. -- Line numbers: - - The marker has no line number, and the line numbers do not jump over it. +- Line numbers and ranges: + - The marker is a line of the block. It has a line number, and line ranges such as `{4}` count it. + - The line numbers do not jump over the skipped code. - Copy and selection: - - The copy button copies the code without the markers. A manual selection never includes the text of a marker. + - The copy button and a manual selection copy the marker as a comment, such as `// ...`. The comment holds the text of the directive, or `...` when it has none. An alias line copies as written. - Screen readers: - - Screen readers read the text of the marker in its place among the lines. + - Screen readers read the text of the marker in its place among the lines, and not the comment. - Print: - Markers print. @@ -169,8 +163,9 @@ Turn the feature off for the whole site with `skippedCode: false`. The plugin th ## Limitations -- The directive needs a comment. JSON has no comments and can use only the `...` alias, so its markers have no text. -- A code walkthrough or scrollycoding step with a marker changes without the animation. The animation does not have the height of the marker. +- The directive needs a comment. JSON has no comments and can use only bare aliases, so its markers have no text. +- The directive goes on a line of its own. On a line with code, the plugin logs a warning and leaves it out. +- During the animation of a code walkthrough or scrollycoding step, a marker line shows empty. - Line numbers do not jump over the skipped code. To start a block at a later number, use the `startLineNumber` attribute of Expressive Code. - The copied code is incomplete, so it can fail to run. Do not use skipped code in a block with a **Run code** or playground button. diff --git a/packages/starlight-codeblocks/src/client/hidden-lines.ts b/packages/starlight-codeblocks/src/client/hidden-lines.ts index 4bf4668..6f444fc 100644 --- a/packages/starlight-codeblocks/src/client/hidden-lines.ts +++ b/packages/starlight-codeblocks/src/client/hidden-lines.ts @@ -17,11 +17,7 @@ function setRun(block: Element, marker: Element, open: boolean) { line.nextElementSibling.classList.toggle(OPEN, open); // Opens a collapsed expandable block or collapsible section that holds the line. if (open && line) unhide(line); - for ( - let el = line?.previousElementSibling; - el?.matches('.scb-callout, .scb-skip-marker'); - el = el.previousElementSibling - ) { + for (let el = line?.previousElementSibling; el?.matches('.scb-callout'); el = el.previousElementSibling) { el.classList.toggle(OPEN, open); } } diff --git a/packages/starlight-codeblocks/src/expressive-code/comments.ts b/packages/starlight-codeblocks/src/expressive-code/comments.ts index 1496e38..3332ea5 100644 --- a/packages/starlight-codeblocks/src/expressive-code/comments.ts +++ b/packages/starlight-codeblocks/src/expressive-code/comments.ts @@ -35,26 +35,18 @@ export interface CommentSyntax { close?: string; } -function commentEntry(language: string, overrides: Record) { +/** The entry of `map` for `language`, under its name or a Shiki alias of it. */ +export function forLanguage(language: string, map: Record): T | undefined { const key = language.toLowerCase(); const info = bundledLanguage(key); const keys = [key, ...(info ? [info.id, ...(info.aliases ?? [])] : [])]; - const own = (syntaxes: Record) => - keys.map((k) => (Object.hasOwn(syntaxes, k) ? syntaxes[k] : undefined)).find(Boolean); - return { keys, syntax: own(overrides) ?? own(defaultCommentSyntax) }; + return keys.map((k) => (Object.hasOwn(map, k) ? map[k] : undefined)).find(Boolean); } export function commentSyntaxFor(language: string, overrides: Record = {}): CommentSyntax[] { - return (commentEntry(language, overrides).syntax ?? []).map((entry) => { + const syntax = forLanguage(language, overrides) ?? forLanguage(language, defaultCommentSyntax); + return (syntax ?? []).map((entry) => { const [open = '', close] = entry.trim().split(/\s+/); return { open, close }; }); } - -/** - * JSON, unless the site gives it a comment syntax. Other languages with no entry may still have comments (F#, Elixir). - */ -export function hasNoComments(language: string, overrides: Record = {}) { - const { keys, syntax } = commentEntry(language, overrides); - return !syntax && keys.includes('json'); -} diff --git a/packages/starlight-codeblocks/src/expressive-code/notation.ts b/packages/starlight-codeblocks/src/expressive-code/notation.ts index 3ae24fc..a2833b2 100644 --- a/packages/starlight-codeblocks/src/expressive-code/notation.ts +++ b/packages/starlight-codeblocks/src/expressive-code/notation.ts @@ -1,14 +1,20 @@ import { AttachedPluginData, type ExpressiveCodeBlock, type ExpressiveCodeLine } from '@expressive-code/core'; -import { type CommentSyntax, commentSyntaxFor, hasNoComments } from './comments.ts'; +import { type CommentSyntax, commentSyntaxFor, forLanguage } from './comments.ts'; import { type CodeblocksPlugin, lineData, lineElement, numberedLines, resolveRange, warn } from './core.ts'; export interface DirectiveSpec { /** The directive takes the text after it, up to the next directive or the end of the comment. */ text?: boolean; - /** On a line of its own at the end of the block, the directive applies after the last line, with `after`. */ - endOfBlock?: boolean; - /** A line that holds only one of these, in a comment, or alone in JSON, is read as the directive. */ - aliases?: string[]; + /** + * The directive stands for a line of its own: that line stays in the block, as a comment with the directive's text, + * or `...`. It takes no `:N`, and does nothing on a line with code. + */ + ownLine?: boolean; + /** + * Lines that are read as the directive, by language, with `*` for every language without an entry: + * a comment that holds only an alias, or a line that holds only a bare alias. + */ + aliases?: { comment?: Record; bare?: Record }; /** For the directives reference page. */ docs?: { description: string; @@ -33,10 +39,6 @@ export interface Directive { text?: string; /** The line of the directive in the code block source, from 1. */ sourceLine: number; - /** The directive comes after its line: see `DirectiveSpec.endOfBlock`. */ - after?: boolean; - /** The leading whitespace of the directive's source line. */ - indent?: string; } const wordChar = /[\w$]/; @@ -141,6 +143,7 @@ function interpret(token: Token, specs: DirectiveSpecs, sourceLine: number) { if (count < 1) return { problem: 'needs a count of 1 or more after the colon, such as `:3`' }; const spec = Object.hasOwn(specs, `code ${match[1]}`) ? specs[`code ${match[1]}`] : undefined; if (!spec) return { problem: 'is not a known directive' }; + if (spec.ownLine && match[2] !== undefined) return { problem: 'takes no count' }; items.push({ spec, directive: { name: `code ${match[1]}`, count, args: [], sourceLine } }); } return { items }; @@ -210,6 +213,8 @@ function findComment(text: string, first: number, syntaxes: CommentSyntax[]) { return best; } +const diffPrefix = /^[+-](?![+-])/; + /** Parses the directives in one line and returns the line without them. */ export function parseLine( text: string, @@ -243,7 +248,7 @@ export function parseLine( const [start, bodyStart, bodyEnd, end] = comment; const body = text.slice(bodyStart, bodyEnd); // Expressive Code strips a diff prefix only later, so `+ // [!code …]` still holds only directives. - const prefix = diff ? (text.match(/^[+-](?![+-])/)?.[0].length ?? 0) : 0; + const prefix = diff ? (text.match(diffPrefix)?.[0].length ?? 0) : 0; const hasCode = text.slice(prefix, start).trim() !== '' || text.slice(end).trim() !== ''; const directives: Directive[] = []; @@ -280,8 +285,15 @@ export function parseLine( else keep(tail); remaining = unescapeDirectives(remaining); + const onlyDirectives = !hasCode && directives.length > 0 && remaining.trim() === ''; + const own = directives.find((directive) => specs[directive.name]?.ownLine); + if (own && onlyDirectives) { + const [open, close] = [text.slice(start, bodyStart), text.slice(bodyEnd, end)]; + const comment = `${open} ${own.text ?? '...'}${close ? ` ${close}` : ''}`; + return { text: text.slice(0, start) + comment, removed: false, directives }; + } // A line that holds only directives goes, as in Shiki's notation transformers. - if (!hasCode && directives.length > 0 && remaining.trim() === '') return { text: '', removed: true, directives }; + if (onlyDirectives) return { text: '', removed: true, directives }; const before = text.slice(0, start); const after = text.slice(end); const newText = @@ -294,58 +306,76 @@ export function parseLine( : text.slice(0, bodyStart) + (directives.length > 0 ? remaining.trimEnd() + (body.match(/\s*$/)?.[0] ?? '') : remaining) + text.slice(bodyEnd); + if (own) { + report(`\`[!${own.name}]\` goes on a line of its own. The line renders without it.`, sourceLine); + directives.splice(directives.indexOf(own), 1); + } return { text: newText, removed: false, directives }; } type Aliases = [alias: string, name: string][]; -const diffPrefix = /^[+-](?![+-])/; +export interface LineAliases { + comment: Aliases; + bare: Aliases; +} -/** - * The name of the directive whose alias is all of `line`, or all of a comment that is all of `line`. - * With `bare`, for a language with no comments, the alias alone on the line. - */ -function aliasOf(line: string, syntaxes: CommentSyntax[], bare: boolean, aliases: Aliases) { - if (aliases.length === 0) return undefined; +/** The name of the directive whose alias is all of `line`, or all of a comment that is all of `line`. */ +function aliasOf(line: string, syntaxes: CommentSyntax[], aliases: LineAliases) { const text = line.trim(); - const bodies = bare - ? [text] - : syntaxes - .filter(({ open, close }) => text.startsWith(open) && (!close || text.endsWith(close))) - .map(({ open, close }) => text.slice(open.length, close ? -close.length : undefined).trim()); - return aliases.find(([alias]) => bodies.includes(alias))?.[1]; + const bodies = syntaxes + .filter(({ open, close }) => text.startsWith(open) && (!close || text.endsWith(close))) + .map(({ open, close }) => text.slice(open.length, close ? -close.length : undefined).trim()); + return (aliases.bare.find(([alias]) => alias === text) ?? + aliases.comment.find(([alias]) => bodies.includes(alias)))?.[1]; } -const aliasesOf = (specs: DirectiveSpecs): Aliases => - Object.entries(specs).flatMap(([name, spec]) => (spec.aliases ?? []).map((alias): [string, string] => [alias, name])); +/** The aliases of every directive in `language`: its own entry, else `*`. */ +export function aliasesFor(specs: DirectiveSpecs, language: string): LineAliases { + const of = (kind: 'comment' | 'bare') => + Object.entries(specs).flatMap(([name, spec]) => { + const map = spec.aliases?.[kind] ?? {}; + return (forLanguage(language, map) ?? map['*'] ?? []).map((alias): [string, string] => [alias, name]); + }); + return { comment: of('comment'), bare: of('bare') }; +} -/** - * Parses every line, and moves the directives of removed lines to the line below them. - * With `bare`, for a language with no comments, only aliases apply. - */ +const specsCache = new WeakMap }>(); + +/** The directives that every plugin declares, once for each list of plugins, and their aliases in `language`. */ +function specsOf(plugins: readonly unknown[], language: string) { + let found = specsCache.get(plugins); + if (!found) { + const specs: DirectiveSpecs = Object.assign( + {}, + ...plugins.map((plugin) => (plugin as CodeblocksPlugin).directives ?? {}), + ); + found = { specs, aliases: new Map() }; + specsCache.set(plugins, found); + } + let aliases = found.aliases.get(language); + if (!aliases) { + aliases = aliasesFor(found.specs, language); + found.aliases.set(language, aliases); + } + return { specs: found.specs, aliases }; +} + +/** Parses every line, and moves the directives of removed lines to the line below them. */ export function parseNotation( lines: string[], syntaxes: CommentSyntax[], specs: DirectiveSpecs, report: Report, diff = false, - bare = false, + aliases: LineAliases = { comment: [], bare: [] }, ): ParsedLine[] { - const aliases = aliasesOf(specs); - const unprefixed = (text: string) => (diff ? text.replace(diffPrefix, '') : text); const parsed = lines.map((text, i): ParsedLine => { - const name = aliasOf(unprefixed(text), syntaxes, bare, aliases); - if (name) return { text: '', removed: true, directives: [{ name, count: 1, args: [], sourceLine: i + 1 }] }; + const name = aliasOf(diff ? text.replace(diffPrefix, '') : text, syntaxes, aliases); + if (name) return { text, removed: false, directives: [{ name, count: 1, args: [], sourceLine: i + 1 }] }; if (syntaxes.length === 0) return { text, removed: false, directives: [] }; return parseLine(text, syntaxes, specs, report, i + 1, diff); }); - // Expressive Code's diff syntax removes the prefix and the indentation that every line shares. - const columns = diff ? diffColumns(lines.filter((_, i) => !parsed[i]?.removed)) : undefined; - parsed.forEach((line, i) => { - const text = lines[i] as string; - const indent = text.slice(columns?.(text) ?? 0).match(/^\s*/)?.[0]; - for (const directive of line.directives) directive.indent = indent; - }); let pending: Directive[] = []; for (const line of parsed) { if (line.removed) { @@ -364,11 +394,7 @@ export function parseNotation( return false; }); } - const last = parsed.findLast((line) => !line.removed); - for (const directive of pending) { - if (last && specs[directive.name]?.endOfBlock) last.directives.push({ ...directive, after: true }); - else report(`\`[!${directive.name}]\` has no line below it.`, directive.sourceLine); - } + for (const directive of pending) report(`\`[!${directive.name}]\` has no line below it.`, directive.sourceLine); return parsed; } @@ -489,28 +515,20 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl preprocessLanguage(context) { const { codeBlock, config } = context; const syntaxes = commentSyntaxFor(codeBlock.language, comments); - const bare = hasNoComments(codeBlock.language, comments); - if (syntaxes.length === 0 && !bare) return; - const specs: DirectiveSpecs = Object.assign( - {}, - ...config.plugins.map((plugin) => (plugin as CodeblocksPlugin).directives ?? {}), - ); + const { specs, aliases } = specsOf(config.plugins, codeBlock.language); + const hasDirectives = syntaxes.length > 0 && /\[\\?!/.test(codeBlock.code); + const candidates = syntaxes.length > 0 ? [...aliases.bare, ...aliases.comment] : aliases.bare; + if (!hasDirectives && !candidates.some(([alias]) => codeBlock.code.includes(alias))) return; const lines = codeBlock.getLines(); // The text markers plugin reads the `useDiffSyntax` meta option only in `preprocessMetadata`. const diff = codeBlock.metaOptions.getBoolean('useDiffSyntax') ?? Boolean(codeBlock.props.useDiffSyntax); - const aliases = aliasesOf(specs); - const hasDirectives = syntaxes.length > 0 && /\[\\?!/.test(codeBlock.code); - const hasAliases = lines.some((line) => - aliasOf(diff ? line.text.replace(diffPrefix, '') : line.text, syntaxes, bare, aliases), - ); - if (!hasDirectives && !hasAliases) return; const parsed = parseNotation( lines.map((line) => line.text), syntaxes, specs, (message, line) => warn(context, message, line), diff, - bare, + aliases, ); const visible = lines.filter((_, i) => !parsed[i]?.removed); const marks = parsed.flatMap(({ directives }, i) => @@ -550,9 +568,12 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl const area = outputSet.has(line) ? output : runSet.has(line) ? run : code; const target = area.indexOf(line); for (const directive of directives) { - // Output and run lines leave the code, so a marker after the block goes after the last line of code. - if (directive.after && area !== code) { - data.directives.push({ ...directive, lines: code.slice(-1) }); + if (area !== code && specs[directive.name]?.ownLine) { + warn( + context, + `\`[!${directive.name}]\` is not in the code, so it shows as a comment.`, + directive.sourceLine, + ); continue; } data.directives.push({ ...directive, lines: area.slice(target, target + directive.count) }); @@ -587,9 +608,10 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl const { removed, specs, diffIndent } = notationData.getOrCreateFor(codeBlock); for (const [line, columns] of diffIndent) line.editText(0, columns, ''); if (syntaxes.length > 0 && /\[\\?!/.test(codeBlock.code)) { + const diff = Boolean(codeBlock.props.useDiffSyntax); for (const line of codeBlock.getLines()) { // Other plugins can edit lines after the first parse, so parse the current text again. - const { text, removed: gone } = parseLine(line.text, syntaxes, specs, () => {}); + const { text, removed: gone } = parseLine(line.text, syntaxes, specs, () => {}, 1, diff); // The first parse kept this line, and blanking it would leave an empty line behind. if (gone && !removed.includes(line)) continue; if (text !== line.text) line.editText(0, line.text.length, text); diff --git a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts index 6140a73..34ec53b 100644 --- a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts +++ b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts @@ -1,8 +1,7 @@ import { type ExpressiveCodeLine, PluginStyleSettings, type UnresolvedStyleValue } from '@expressive-code/core'; -import { type Element, h, select } from '@expressive-code/core/hast'; +import { addClassName, h, select } from '@expressive-code/core/hast'; import { uiTexts } from '../translations.ts'; -import { type CodeblocksPlugin, insertAfter, insertBefore, lineElement } from './core.ts'; -import { isHiddenLine } from './hidden-lines.ts'; +import { type CodeblocksPlugin, lineElement } from './core.ts'; import { inlineMarkdown } from './inline-markdown.ts'; import { getRenderedDirectives } from './notation.ts'; import { markerColours, markerStyles, PREFIX } from './styles.ts'; @@ -21,19 +20,32 @@ declare module '@expressive-code/core' { const styleSettings = new PluginStyleSettings({ defaultValues: { codeblocksSkippedCode: markerColours } }); export interface SkippedCodeSettings { - /** Lines that stand for `[!code skip]`, as the whole of a comment, or alone in JSON. None by default. */ - aliases?: string[]; + /** Comments that stand for `[!code skip]` when they hold only an alias, by language, with `*` for the others. */ + commentAliases?: Record; + /** Lines that stand for `[!code skip]` when they hold only an alias, by language, with `*` for the others. */ + bareAliases?: Record; } -/** Shows a marker where `[!code skip]` stands for code that the block leaves out. */ -export function pluginSkippedCode({ aliases = [] }: SkippedCodeSettings = {}): CodeblocksPlugin { +export const defaultSkipAliases = { comment: { '*': ['...'] }, bare: { json: ['...'] } }; + +const trimmed = (aliases: Record) => + Object.fromEntries(Object.entries(aliases).map(([language, list]) => [language, list.map((alias) => alias.trim())])); + +/** Draws a `[!code skip]` line, which stands for code that the block leaves out, as a marker. */ +export function pluginSkippedCode({ + commentAliases = {}, + bareAliases = {}, +}: SkippedCodeSettings = {}): CodeblocksPlugin { return { name: 'starlight-codeblocks:skipped-code', directives: { 'code skip': { text: true, - endOfBlock: true, - aliases: aliases.map((alias) => alias.trim()), + ownLine: true, + aliases: { + comment: trimmed({ ...defaultSkipAliases.comment, ...commentAliases }), + bare: trimmed({ ...defaultSkipAliases.bare, ...bareAliases }), + }, docs: { description: 'Shows a marker in place of code that the block leaves out.', args: 'Optional. The text of the marker.', @@ -45,37 +57,32 @@ export function pluginSkippedCode({ aliases = [] }: SkippedCodeSettings = {}): C styleSettings, baseStyles: ({ cssVar }) => ` ${markerStyles(cssVar, `${PREFIX}-skip-marker`, `${PREFIX}-skip-text`, 'codeblocksSkippedCode', 'dotted')} -.${PREFIX}-skip-marker { padding-inline-start: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}); } -/* An element, because a flex container drops text that is only whitespace. */ -.${PREFIX}-skip-indent { white-space: pre; line-height: 0; } -/* A marker between hidden lines shows with them. */ -.${PREFIX}-skip-hidden:not(.${PREFIX}-hidden-open) { display: none; } +/* Not zero width or in a flex container: Chromium leaves either out of a manual selection. */ +.${PREFIX}-skip-source { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: pre; } +.${PREFIX}-skip-marker { display: inline-flex; position: static; } +.${PREFIX}-skip-marker::before { inset-inline: ${cssVar('codePaddingInline')}; } +@media (hover: none) { + .ec-line:first-child .${PREFIX}-skip-marker::before { inset-inline-end: calc(${cssVar('codePaddingInline')} + 2.5rem); } +} `, hooks: { postprocessRenderedBlock(context) { - const directives = getRenderedDirectives(context, 'code skip'); - const code = directives.length > 0 && select('pre > code', context.renderData.blockAst); - if (!code) return; const say = uiTexts(context.locale); - const { codeBlock } = context; - const all = codeBlock.getLines(); - const hiddenBefore = (line: ExpressiveCodeLine) => - isHiddenLine(codeBlock, line) && isHiddenLine(codeBlock, all[all.indexOf(line) - 1] as ExpressiveCodeLine); - // Markers after a line keep their source order. - const lastAfter = new Map(); - for (const { lines, text, after, indent } of directives) { - const line = lines[0]; - const el = line && lineElement(line); - if (!el) continue; - const hidden = !after && hiddenBefore(line); - const marker = h('div', { class: `${PREFIX}-skip-marker${hidden ? ` ${PREFIX}-skip-hidden` : ''}` }, [ - ...(indent ? [h('span', { class: `${PREFIX}-skip-indent` }, indent)] : []), - h('span', { class: `${PREFIX}-skip-text` }, text ? inlineMarkdown(text) : say('skippedCode.marker')), - ]); - if (after) { - insertAfter(code, lastAfter.get(el) ?? el, marker); - lastAfter.set(el, marker); - } else insertBefore(code, el, marker); + for (const { lines, text } of getRenderedDirectives(context, 'code skip')) { + const line = lines[0] as ExpressiveCodeLine; + const el = lineElement(line); + const code = el && select('.code', el); + if (!code) continue; + addClassName(el, `${PREFIX}-skip-line`); + // A real diff keeps its `+` or `-` prefix in the text. + const indent = line.text.match(/^(?:[+-](?![+-]))?\s*/)?.[0] ?? ''; + code.children = [ + ...(indent ? [{ type: 'text' as const, value: indent }] : []), + h('span', { class: `${PREFIX}-skip-source`, ariaHidden: 'true' }, line.text.slice(indent.length)), + h('span', { class: `${PREFIX}-skip-marker` }, [ + h('span', { class: `${PREFIX}-skip-text` }, text ? inlineMarkdown(text) : say('skippedCode.marker')), + ]), + ]; } }, }, diff --git a/packages/starlight-codeblocks/src/expressive-code/styles.ts b/packages/starlight-codeblocks/src/expressive-code/styles.ts index b777bff..76110c2 100644 --- a/packages/starlight-codeblocks/src/expressive-code/styles.ts +++ b/packages/starlight-codeblocks/src/expressive-code/styles.ts @@ -100,7 +100,7 @@ export const markerStyles = ( position: absolute; top: 50%; inset-inline: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}) ${cssVar('codePaddingInline')}; - border-top: 1px ${border} ${cssVar(`${group}.rule` as never)}; + border-top: 1px ${border} ${cssVar(`${group}.rule`)}; transform: translateY(-50%); } /* Where the copy button always shows, it sits over the end of the first line. */ @@ -112,7 +112,7 @@ export const markerStyles = ( z-index: 1; padding: 0.05em 0.65em; border-radius: 999px; - background: ${cssVar(`${group}.badgeBackground` as never)}; + background: ${cssVar(`${group}.badgeBackground`)}; font-size: 0.8125em; line-height: 1.6; }`; diff --git a/packages/starlight-codeblocks/src/options.ts b/packages/starlight-codeblocks/src/options.ts index bc4d7c9..6519368 100644 --- a/packages/starlight-codeblocks/src/options.ts +++ b/packages/starlight-codeblocks/src/options.ts @@ -2,6 +2,7 @@ import { nextflow } from './adapters/nextflow.ts'; import { python } from './adapters/python.ts'; import type { FileIconLanguage, FileIconSet, FileIconStyle } from './expressive-code/file-icons.ts'; import { fileIconSets, isCssColour } from './expressive-code/file-icons.ts'; +import { defaultSkipAliases } from './expressive-code/skipped-code.ts'; import { type SwatchDelimiters, type SwatchFormat, @@ -89,7 +90,7 @@ export interface CodeblocksOptions { annotations?: false | { style?: 'filled' | 'outline' }; footnotes?: false | { sticky?: boolean; style?: 'filled' | 'outline' }; hiddenLines?: false; - skippedCode?: false | { aliases?: string[] }; + skippedCode?: false | { commentAliases?: Record; bareAliases?: Record }; shellCopy?: false | { prompts?: string[] }; wordDiff?: false | { minSimilarity?: number }; splitDiff?: false | { view?: 'unified' | 'split'; switch?: boolean; sync?: boolean }; @@ -195,6 +196,8 @@ const isString = (value: unknown) => typeof value === 'string'; const isStringArray = (value: unknown) => Array.isArray(value) && value.every(isString); const isRecordOf = (valid: (value: unknown) => boolean) => (value: unknown) => isObject(value) && Object.values(value).every(valid); +const isAliasList = (value: unknown) => + isStringArray(value) && (value as string[]).every((alias) => alias.trim() !== ''); const oneOf = (...values: string[]) => (value: unknown) => @@ -324,12 +327,19 @@ export const optionsReference: Record = { page: 'features/skipped-code', off: '`[!code skip]` then stays in the code as written.', fields: { - aliases: { - type: 'string[]', - default: [], + commentAliases: { + type: 'Record', + default: defaultSkipAliases.comment, + description: + 'Comments that stand for `[!code skip]` when they hold only an alias, such as `// ...`, by language. `*` applies to every language without its own entry, and `[]` turns aliases off for a language. Your keys merge over the defaults.', + valid: isRecordOf(isAliasList), + }, + bareAliases: { + type: 'Record', + default: defaultSkipAliases.bare, description: - "Lines that stand for `[!code skip]`: a comment that holds only an alias, such as `// ...`, or the alias alone on its line in JSON, which has no comments. `['...']` reads the `// ...` comments of existing pages as markers, which changes those pages: see the feature page.", - valid: (value) => isStringArray(value) && (value as string[]).every((alias) => alias.trim() !== ''), + 'Lines that stand for `[!code skip]` when they hold only an alias, with no comment, by language, such as `...` in JSON. `*` applies to every language without its own entry, and `[]` turns aliases off for a language. Your keys merge over the defaults.', + valid: isRecordOf(isAliasList), }, }, }, diff --git a/packages/starlight-codeblocks/test/notation.test.ts b/packages/starlight-codeblocks/test/notation.test.ts index a17659f..0757228 100644 --- a/packages/starlight-codeblocks/test/notation.test.ts +++ b/packages/starlight-codeblocks/test/notation.test.ts @@ -1,6 +1,6 @@ import { describe, expect, test } from 'vitest'; -import { commentSyntaxFor, hasNoComments } from '../src/expressive-code/comments.ts'; -import { type DirectiveSpecs, parseLine, parseNotation } from '../src/expressive-code/notation.ts'; +import { commentSyntaxFor, forLanguage } from '../src/expressive-code/comments.ts'; +import { aliasesFor, type DirectiveSpecs, parseLine, parseNotation } from '../src/expressive-code/notation.ts'; const specs: DirectiveSpecs = { 'code focus': {}, @@ -10,7 +10,11 @@ const specs: DirectiveSpecs = { mention: {}, callout: { text: true }, link: {}, - 'code skip': { text: true, endOfBlock: true, aliases: ['...'] }, + 'code skip': { + text: true, + ownLine: true, + aliases: { comment: { '*': ['...'], md: [] }, bare: { json: ['...'], yaml: ['…'] } }, + }, }; const js = commentSyntaxFor('js'); @@ -159,24 +163,40 @@ describe('parseNotation', () => { ]); }); - test('moves an endOfBlock directive at the end of the block to the last line, after it', () => { - const { parsed, problems } = parseBlock(['a()', 'b()', '// [!code skip] Rest', '// [!code focus]']); - expect(problems).toEqual([[expect.stringContaining('has no line below it'), 4]]); - expect(parsed[1]?.directives).toMatchObject([{ name: 'code skip', text: 'Rest', after: true }]); - expect(parseBlock(['// [!code skip]']).problems).toEqual([[expect.stringContaining('has no line below it'), 1]]); + test('keeps the line of an ownLine directive, as a comment with its text', () => { + const { parsed, problems } = parseBlock(['a()', ' // [!code skip] Rest', '/* [!code skip] */']); + expect(problems).toEqual([]); + expect(parsed.map(({ text, removed }) => [text, removed])).toEqual([ + ['a()', false], + [' // Rest', false], + ['/* ... */', false], + ]); + expect(parsed[1]?.directives).toMatchObject([{ name: 'code skip', text: 'Rest' }]); + expect(parseLine('+ // [!code skip]', js, specs, () => {}, 1, true).text).toBe('+ // ...'); + }); + + test('drops an ownLine directive on a line with code, or with a count', () => { + const { parsed, problems } = parseBlock(['a() // [!code skip]', '// [!code skip:2]', 'b()']); + expect(parsed[0]).toMatchObject({ text: 'a()', directives: [] }); + expect(parsed[1]).toMatchObject({ text: '// [!code skip:2]', directives: [] }); + expect(problems).toEqual([ + [expect.stringContaining('goes on a line of its own'), 1], + [expect.stringContaining('takes no count'), 2], + ]); }); - test('reads a line that holds only an alias, in a comment or in a language with no comments', () => { - const skip = (lines: string[], lang = 'js', comments = {}) => - parseNotation(lines, commentSyntaxFor(lang, comments), specs, () => {}, false, hasNoComments(lang, comments)).map( + test('reads a line that holds only an alias, in a comment or bare, by language', () => { + const skip = (lines: string[], lang = 'js') => + parseNotation(lines, commentSyntaxFor(lang), specs, () => {}, false, aliasesFor(specs, lang)).map( ({ removed, directives }) => (removed ? 'removed' : directives.map((d) => d.name).join()), ); - expect(skip(['a()', ' // ...', 'b()'])).toEqual(['', 'removed', 'code skip']); - expect(skip(['a()', '/* ... */'])).toEqual(['code skip', 'removed']); - expect(skip(['{', ' ...', '}'], 'json')).toEqual(['', 'removed', 'code skip']); + expect(skip(['a()', ' // ...', 'b()'])).toEqual(['', 'code skip', '']); + expect(skip(['a()', '/* ... */'])).toEqual(['', 'code skip']); + expect(skip(['{', ' ...', '}'], 'json')).toEqual(['', 'code skip', '']); expect(skip(['a() // ...', '// ... more', '...', '//...x', '[...a]'])).toEqual(['', '', '', '', '']); - expect(skip(['def f():', ' ...', '# ...'], 'py')).toEqual(['', 'code skip', 'removed']); - expect(skip(['...', 'a'], 'json', { json: [] })).toEqual(['', '']); + expect(skip(['def f():', ' ...', '# ...'], 'py')).toEqual(['', '', 'code skip']); + expect(skip([''], 'md')).toEqual(['']); + expect(skip(['a: 1', '…', '...', '# ...'], 'yml')).toEqual(['', 'code skip', '', 'code skip']); }); }); @@ -184,9 +204,8 @@ test('commentSyntaxFor uses the built-in map, Shiki aliases and the options', () expect(commentSyntaxFor('Python')).toEqual([{ open: '#', close: undefined }]); expect(commentSyntaxFor('css')).toEqual([{ open: '/*', close: '*/' }]); expect(commentSyntaxFor('json')).toEqual([]); - expect(hasNoComments('json')).toBe(true); - expect(hasNoComments('json', { json: ['//'] })).toBe(false); - expect(hasNoComments('fsharp')).toBe(false); + expect(forLanguage('yml', { yaml: 1 })).toBe(1); + expect(forLanguage('fsharp', { json: 1 })).toBeUndefined(); expect(commentSyntaxFor('pwsh')).toEqual(commentSyntaxFor('powershell')); expect(commentSyntaxFor('shellsession')).toEqual([{ open: '#', close: undefined }]); expect(commentSyntaxFor('pwsh', { powershell: ['//'] })).toEqual([{ open: '//', close: undefined }]); diff --git a/packages/starlight-codeblocks/test/options.test.ts b/packages/starlight-codeblocks/test/options.test.ts index 03a01ec..dddfac8 100644 --- a/packages/starlight-codeblocks/test/options.test.ts +++ b/packages/starlight-codeblocks/test/options.test.ts @@ -14,7 +14,7 @@ test('turns every feature on with defaults, in new objects on each call', () => expect(options.footnotes).toEqual({ sticky: false, style: 'outline' }); expect(options.shellCopy).toEqual({ prompts: ['$ ', '> '] }); expect(options.expandable).toEqual({ lines: 12, auto: false }); - expect(options.skippedCode).toEqual({ aliases: [] }); + expect(options.skippedCode).toEqual({ commentAliases: { '*': ['...'] }, bareAliases: { json: ['...'] } }); expect(options.inlineHighlighting).toEqual({ defaultLanguage: false }); expect(options.playgrounds).toEqual({}); expect(options.walkthrough).toEqual({ start: 1 }); @@ -63,7 +63,9 @@ test('rejects options that are not valid, with an OptionsError that names the op [{ annotations: { style: 'solid' } }, '`annotations.style` must be'], [{ footnotes: { style: 'solid' } }, '`footnotes.style` must be'], [{ expandable: { lines: 0 } }, '`expandable.lines` must be number, got 0'], - [{ skippedCode: { aliases: [' '] } }, '`skippedCode.aliases` must be'], + [{ skippedCode: { aliases: ['...'] } }, 'unknown option `skippedCode.aliases`'], + [{ skippedCode: { commentAliases: { '*': [' '] } } }, '`skippedCode.commentAliases` must be'], + [{ skippedCode: { bareAliases: { json: '...' } } }, '`skippedCode.bareAliases` must be'], [{ wordDiff: { minSimilarity: 2 } }, '`wordDiff.minSimilarity`'], [{ lineStates: { states: { todo: { label: 'To do', colour: '#fff' } } } }, '`lineStates.states` must be'], [{ lineStates: { states: { focus: { label: 'F', colour } } } }, '`lineStates.states`'], diff --git a/packages/starlight-codeblocks/test/skipped-code.test.ts b/packages/starlight-codeblocks/test/skipped-code.test.ts index eab2e74..a44f6c6 100644 --- a/packages/starlight-codeblocks/test/skipped-code.test.ts +++ b/packages/starlight-codeblocks/test/skipped-code.test.ts @@ -1,101 +1,109 @@ +import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'; import { expect, test } from 'vitest'; import { block, render } from './render.ts'; -const marker = (html: string) => html.match(/
.*?<\/div>/g) ?? []; -const dots = { skippedCode: { aliases: ['...'] } }; +const skipLines = (html: string) => + html.match(/
]*>.*?<\/div><\/div>/g) ?? []; -test('puts a marker where a [!code skip] line was, and leaves it out of the copied text', async () => { +test('draws a [!code skip] line as a marker, and copies it as a comment', async () => { const { html, copyText, warnings } = await render( block('js', 'function connect() {', ' // [!code skip]', ' return socket;', '}'), ); - expect(marker(html)).toEqual([ - '
Code not shown
', + expect(skipLines(html)).toEqual([ + '
Code not shown
', ]); - expect(html.indexOf('scb-skip-marker')).toBeLessThan(html.indexOf('return')); - expect(html.indexOf('scb-skip-marker')).toBeGreaterThan(html.indexOf('connect')); - expect(copyText).toBe('function connect() {\n return socket;\n}'); + expect(copyText).toBe('function connect() {\n // ...\n return socket;\n}'); expect(warnings).toEqual([]); }); -test('takes the marker text from the directive, with inline Markdown', async () => { - const { html } = await render(block('py', 'import os', '# [!code skip] The `main()` function', 'main()')); - expect(marker(html)).toEqual([ - '
The main() function
', - ]); -}); - -test('puts a marker after the last line, from a [!code skip] line at the end', async () => { - const { html, copyText, warnings } = await render(block('js', 'const a = 1;', '// [!code skip] More')); - expect(html).toMatch(/>1<.*
More<\/span><\/div><\/code>/); - expect(copyText).toBe('const a = 1;'); - expect(warnings).toEqual([]); -}); - -test('puts a marker above a line with a trailing [!code skip]', async () => { - const { html } = await render(block('js', 'a();', 'b(); // [!code skip]')); - expect(html).toMatch(/>a<.*scb-skip-marker.*>b { + const { html, copyText } = await render(block('py', 'import os', '# [!code skip] The `main()` function', 'main()')); + expect(skipLines(html)).toEqual([expect.stringContaining('The main() function')]); + expect(copyText).toBe('import os\n# The `main()` function\nmain()'); }); -test('puts markers at the end of a block in source order', async () => { - const { html } = await render(block('js', 'a();', '// [!code skip] One', '// [!code skip] Two')); - expect(html).toMatch(/One.*Two/); +test('counts a [!code skip] line in line numbers and ranges', async () => { + const { html } = await render(block('js {3}', 'a();', '// [!code skip]', 'b();')); + expect(html).toMatch(/
.*?b<\/span>/); + const numbered = await render(block('js showLineNumbers', 'a();', '// [!code skip]', 'b();'), {}, [ + pluginLineNumbers(), + ]); + expect(skipLines(numbered.html)).toEqual([expect.stringMatching(/class="ln"[^>]*>2a<.*scb-skip-line.*More<\/span><\/span><\/div><\/div><\/code>/); }); -test('hides a marker between hidden lines with them, but not one above a run', async () => { +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(marker(html)).toEqual([expect.stringContaining('scb-skip-marker scb-skip-hidden">')]); - const above = await render(block('js hidden={2-3}', 'a();', '// [!code skip] Above', 'b();', 'c();')); - expect(marker(above.html)).toEqual([expect.stringContaining('class="scb-skip-marker">')]); + expect(skipLines(html)).toEqual([expect.stringContaining('scb-skip-line scb-hidden-line scb-no-print')]); }); -test('reads a directive line with a diff prefix, at the indentation that readers see', async () => { - const { html, copyText } = await render( - block('diff lang="js"', ' function f() {', '+ // ...', '+ return 1;', ' }'), - dots, - ); - expect(marker(html)).toEqual([expect.stringContaining(' ')]); - expect(copyText).toBe('function f() {\n return 1;\n}'); +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('puts a marker at the end of a block after the last line of code, not after output lines', async () => { - const { html, warnings } = await render(block('sh', 'make', '# [!output]', 'built', '# [!code skip]')); +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(html).toMatch(/make.*scb-skip-marker/); + expect(skipLines(html)).toEqual([expect.stringContaining('More')]); }); -test('leaves `...` lines as written by default, so ranges keep their lines', async () => { - const md = block('js {3}', 'a();', '// ...', 'b();'); - expect((await render(md)).html).toBe((await render(md, { skippedCode: false })).html); +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;', '}'), dots); +test('reads `// ...` in every language with comments, and bare `...` in JSON, by default, and copies them as written', async () => { + 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,', ' ...', '}'), dots); - expect(marker(json.html)).toHaveLength(1); - expect(json.copyText).toBe('{\n "a": 1,\n}'); + 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 `...` that is code, or that has more text, as written', async () => { +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('js', 'f(...args) // ...', '// ... more', '// [...]', '...'), block('json', '[', ' "..."', ']'), - block('fsharp', 'let f () =', ' ...'), ]) { - expect(marker((await render(md, dots)).html)).toEqual([]); + expect(skipLines((await render(md)).html)).toEqual([]); } }); -test('takes custom aliases, and none by default', async () => { - const md = block('js', 'a();', '// …', '// [...]', 'b();'); - expect(marker((await render(md, { skippedCode: { aliases: ['…', '[...]'] } })).html)).toHaveLength(2); - const { html, copyText } = await render(block('js', 'a();', '// ...', 'b();')); - expect(marker(html)).toEqual([]); - expect(copyText).toBe('a();\n// ...\nb();'); +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 () => { diff --git a/skills/starlight-codeblocks/SKILL.md b/skills/starlight-codeblocks/SKILL.md index 39506a5..9acb4b1 100644 --- a/skills/starlight-codeblocks/SKILL.md +++ b/skills/starlight-codeblocks/SKILL.md @@ -77,7 +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 `// ...` with `skippedCode.aliases` | A marker takes the place of the code. The copied code is incomplete. | +| 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. | @@ -166,7 +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, if the site sets `skippedCode.aliases: ['...']`. It also reads `...` alone on its line in JSON. Those lines leave the code and the copied code, so line ranges after them, such as `{4}` or `ins={4}`, count different lines. Check the ranges of each block with `// ...` when the site turns this on. To keep `// ...` as code in one block, add text to the comment, such as `// ... and so on`. +- 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. diff --git a/skills/starlight-codeblocks/references/configuration.md b/skills/starlight-codeblocks/references/configuration.md index 4c72fff..0a9af90 100644 --- a/skills/starlight-codeblocks/references/configuration.md +++ b/skills/starlight-codeblocks/references/configuration.md @@ -32,7 +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` | `aliases`: comments, and JSON lines, that are the same as `[!code skip]`, default `[]`. `['...']` reads `// ...` as a marker and changes existing pages | Skipped code | +| `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 637fd74..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. So does a step with a callout, a hidden lines marker or a skipped code marker. +- 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 de8089d..8b312ef 100644 --- a/skills/starlight-codeblocks/references/readability.md +++ b/skills/starlight-codeblocks/references/readability.md @@ -43,11 +43,11 @@ createServer(handler).listen(port); Docs: https://ewels.github.io/starlight-codeblocks/features/skipped-code/ -Use where an example shows part of a file and leaves code out. A marker takes the place of a `// ...` comment, so readers do not read it as code. Use hidden lines instead if the copied code must run. +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, or at the end of the line below that place | +| `[!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 @@ -58,13 +58,13 @@ app.get('/users', async (req, res) => { ``` - The marker is a dotted rule with a badge, at the indentation of the directive line. It is not a button. -- A directive line at the end of the block puts the marker after the last line. -- The copied code has no marker, and no skipped code. Do not use it in a block with a playground or the **Run code** button. -- Line numbers do not jump over the marker. -- Aliases: `skippedCode.aliases` (default `[]`) sets the lines that are the same as `[!code skip]`. By default, `// ...` stays in the code as written. `['...']` reads a line that holds only a comment with only `...` in it (`// ...`, `# ...`) as a marker. In JSON, which has no comments, it reads `...` alone on its line. In Python and YAML, a bare `...` stays as code. -- The aliases change existing pages: the `// ...` lines leave the code, so line ranges after them, such as `{4}` or `ins={4}`, count different lines. Check those blocks when you set the option. -- With the aliases, 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`. -- A code walkthrough or scrollycoding step with a marker changes without the animation. +- 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 From 47415ca028c64e7a316affb891c9158fd24ab684 Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Wed, 18 Nov 2026 08:27:49 +0100 Subject: [PATCH 10/11] docs: add callouts, a line permalinks example and the alias defaults to the skipped code page Co-Authored-By: Claude Opus 5.5 --- .../content/docs/features/skipped-code.mdx | 29 ++++++++++++++++--- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/features/skipped-code.mdx b/docs/src/content/docs/features/skipped-code.mdx index d658131..4da514a 100644 --- a/docs/src/content/docs/features/skipped-code.mdx +++ b/docs/src/content/docs/features/skipped-code.mdx @@ -43,7 +43,11 @@ Put the directive on its own line where the code is left out. That line shows as Many pages already use `// ...` for code that they leave out. These lines are the same as `[!code skip]` by default, so existing pages show markers with no changes. A line is an alias if it holds one of these, and nothing else: - A comment alias: a comment with only the alias in it, in the comment syntax of the language, such as `// ...`, `# ...`, `/* ... */` or ``. By default, `...` in every language. -- A bare alias: the alias with no comment. By default, `...` in JSON, which has no comments, so the directive cannot go in a JSON block. +- A bare alias: the alias with no comment. By default, `...` in JSON. + +:::note[JSON] +JSON has no comments, so a JSON block cannot hold the `[!code skip]` directive. The default config has a bare alias for JSON, `bareAliases: { json: ['...'] }`, so write `...` alone on a line instead. +::: This JSON block shows two markers: @@ -64,14 +68,14 @@ export const json = ` An alias changes only how the line looks. The line keeps its line number, line ranges count it, and the copied code has the `// ...` as written. An alias takes no text: for a marker with text, write `[!code skip] text`. -Set `skippedCode.commentAliases` and `skippedCode.bareAliases` to change the aliases. Each is a list of aliases for each language, and `*` applies to every language without its own entry. Your entries merge over the defaults, and `[]` turns aliases off for a language: +Set `skippedCode.commentAliases` and `skippedCode.bareAliases` to change the aliases. Each is a list of aliases for each language, and `*` applies to every language without its own entry. The defaults are `commentAliases: { '*': ['...'] }` and `bareAliases: { json: ['...'] }`. Your entries merge over them, and `[]` turns aliases off for a language: ```js title="astro.config.mjs" codeblocks({ skippedCode: { - // `// …` too, in every language, and no comment aliases in Python + // [!callout /commentAliases/] `// …` as well as `// ...`, and no comment aliases in Python. commentAliases: { '*': ['...', '…'], python: [] }, - // `...` with no comment in YAML, as well as in JSON + // [!callout /bareAliases/] `...` with no comment in YAML. JSON keeps its default. bareAliases: { yaml: ['...'] }, }, }); @@ -138,6 +142,23 @@ volumes: +### Link to lines after a marker + +The marker is a line of the block, so it has a line number. With [line permalinks](/starlight-codeblocks/features/line-permalinks/), which the `id` attribute turns on, each number is a link. The `app.get` line below is line 3, as in the source: + +export const permalinks = ` +\`\`\`js title="routes.js" id="routes" +const app = express(); +// [!code skip] Not shown: Middleware and settings +app.get('/users', async (req, res) => { + const users = await db.users.findAll(); + res.json(users); +}); +\`\`\` +`; + + + ## Behaviour - The marker: From b524f3e4c6fb1c1e10cda54ccebf84a55d2a3a60 Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Wed, 18 Nov 2026 08:51:24 +0100 Subject: [PATCH 11/11] skipped-code: fix review findings in diffs, line states, output, mixed directives and walkthroughs - Read a `+` or `-` prefix in the second parse only in a real diff, which Expressive Code leaves as written - Replace only the code of a skip line, so line state labels and messages stay - Give no warning for an alias such as `# ...` in output or run code - Give the text of a dropped `[!code skip]` to the next directive that takes text - Read a skip line as its comment in readTokens, and skip the walkthrough animation when a skip marker shows - Check each line for an alias before the full parse, not any `...` in the block - Remove the unused insertAfter and a stale order comment, reuse diffLine, and keep hidden line positioning out of markerStyles - Rewrite the CHANGELOG entry for the current design Co-Authored-By: Claude Opus 5.5 --- packages/starlight-codeblocks/CHANGELOG.md | 2 +- .../src/components/animate.ts | 4 +- .../src/components/tokens.ts | 4 +- .../src/expressive-code/core.ts | 16 +++---- .../src/expressive-code/hidden-lines.ts | 9 ++++ .../src/expressive-code/index.ts | 1 - .../src/expressive-code/notation.ts | 44 +++++++++++-------- .../src/expressive-code/skipped-code.ts | 19 +++++--- .../src/expressive-code/styles.ts | 7 --- .../test/skipped-code.test.ts | 37 ++++++++++++++++ 10 files changed, 97 insertions(+), 46 deletions(-) diff --git a/packages/starlight-codeblocks/CHANGELOG.md b/packages/starlight-codeblocks/CHANGELOG.md index d3d6871..29f7bdf 100644 --- a/packages/starlight-codeblocks/CHANGELOG.md +++ b/packages/starlight-codeblocks/CHANGELOG.md @@ -7,7 +7,7 @@ - Markdown plugins: `starlight-codeblocks/markdown` exports a Markdown plugin for each feature that changes Markdown, such as `mdastCodeTabs()`, and `mdastCodeblocks()` for all of them. `codeblocks()` adds only the ones that the Markdown processor does not already list, in the correct order among them. A listed plugin for a feature that is off stops the build (#36) - Split diff: a **Unified** and **Split** switch in 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 GitHub pull request does. `splitDiff.view`, `splitDiff.switch` and `splitDiff.sync` set the start view, remove the switch and stop it syncing across the page (#37) - Untitled blocks with title bar controls use the tab bar colours of titled blocks (#37) -- Skipped code: `[!code skip]` shows a marker in place of code that a block leaves out, at the indentation of its line. The text after the directive goes in the marker, else it reads "Code not shown". A directive on its own line at the end of a block puts the marker after the last line. `skippedCode.aliases: ['...']` also reads a comment that holds only `...`, such as `// ...`, and `...` alone on its line in JSON. The aliases are off by default, because they change the line ranges of existing pages. The copied code leaves out the marker. `skippedCode: false` turns it off (#28) +- Skipped code: `[!code skip]` on its own line shows a marker in place of code that a block leaves out, at the indentation of its line. The text after the directive goes in the marker, else it reads "Code not shown". The line keeps its line number, and copies as a comment with the text, such as `// Not shown: Imports`. A comment that holds only `...`, such as `// ...`, and `...` alone on a line in JSON, also show as markers and copy as written. `skippedCode.commentAliases` and `skippedCode.bareAliases` change these aliases for each language. `skippedCode: false` turns the feature off (#28) ## 1.4.1 diff --git a/packages/starlight-codeblocks/src/components/animate.ts b/packages/starlight-codeblocks/src/components/animate.ts index cab86ad..8cff6cd 100644 --- a/packages/starlight-codeblocks/src/components/animate.ts +++ b/packages/starlight-codeblocks/src/components/animate.ts @@ -42,8 +42,8 @@ export function animate(group: HTMLElement, from: StepTokens, to: StepTokens) { if (real.length !== lines(to).length - 1) return () => {}; // The tokens have no line backgrounds or diff markers, so a diff would lose them until the animation ends. if (code.querySelector('.ec-line:is(.ins, .del)')) return () => {}; - // Callouts, hidden-line markers and section summaries take up height but have no tokens, so the block would jump. - const rows = code.querySelectorAll(':scope > :not(.ec-line, details), summary'); + // Callouts, hidden-line and skipped code markers, and section summaries change the height of the block, so it would jump. + const rows = code.querySelectorAll(':scope > :not(.ec-line, details), summary, .scb-skip-line'); if ([...rows].some((row) => row.checkVisibility())) return () => {}; const style = getComputedStyle(group.querySelector('figure') ?? group); const i = style.getPropertyValue('--ec-codeblocksWalkthrough-themeIndex').trim() || '0'; diff --git a/packages/starlight-codeblocks/src/components/tokens.ts b/packages/starlight-codeblocks/src/components/tokens.ts index 6e4ecb5..1b5931c 100644 --- a/packages/starlight-codeblocks/src/components/tokens.ts +++ b/packages/starlight-codeblocks/src/components/tokens.ts @@ -16,6 +16,8 @@ export interface Token { // Decorations that other features add inside a line. Keep in step with their unselectable elements. const DECORATIONS = `button, input, select, [popover], [aria-hidden="true"], .${DECORATION}`; +// The comment that a skipped code marker stands for, which is the line's code. +const SKIP_SOURCE = '.scb-skip-source'; /** The code lines of a block, without the lines that other plugins add, such as a collapsed section's summary. */ export function codeLines(root: Element): Element[] { @@ -44,7 +46,7 @@ export function readTokens(figure: Element): { code: string; lines: Token[][] } if (!content) continue; tokens.push({ content, offset, htmlStyle: styles.join(';') || undefined }); offset += content.length; - } else if (node.type === 'element' && !matches(DECORATIONS, node)) { + } else if (node.type === 'element' && (matches(SKIP_SOURCE, node) || !matches(DECORATIONS, node))) { const style = String(node.properties.style ?? ''); walk(node.children, style.startsWith('--') ? [...styles, style] : styles); } diff --git a/packages/starlight-codeblocks/src/expressive-code/core.ts b/packages/starlight-codeblocks/src/expressive-code/core.ts index 9c6cda9..0651c79 100644 --- a/packages/starlight-codeblocks/src/expressive-code/core.ts +++ b/packages/starlight-codeblocks/src/expressive-code/core.ts @@ -18,6 +18,7 @@ import { type ElementContent, EXIT, h, + matches, type Parents, select, selectAll, @@ -96,6 +97,8 @@ const decorations = [ * Gives each decoration the one class that tools reading the HTML can drop, such as starlight-llms-txt, * and keeps it out of the Pagefind index. Keep the list in step with new decorations. */ +export const isDecoration = (node: ElementContent) => node.type === 'element' && matches(decorations, node); + export function markDecorations(root: Parents) { for (const element of selectAll(decorations, root)) { const classes = element.properties.className as string[]; @@ -112,25 +115,18 @@ const lineElements = new WeakMap(); */ export const lineElement = (line: ExpressiveCodeLine) => lineElements.get(line); -function insertAt(offset: number, root: Parents, target: Element, nodes: ElementContent[]) { +/** Inserts `nodes` before `target`, wherever it is in `root`. */ +export function insertBefore(root: Parents, target: Element, ...nodes: ElementContent[]) { visit( root, (node) => node === target, (_, index, parent) => { - if (parent && index !== undefined) parent.children.splice(index + offset, 0, ...nodes); + if (parent && index !== undefined) parent.children.splice(index, 0, ...nodes); return EXIT; }, ); } -/** Inserts `nodes` before `target`, wherever it is in `root`. */ -export const insertBefore = (root: Parents, target: Element, ...nodes: ElementContent[]) => - insertAt(0, root, target, nodes); - -/** Inserts `nodes` after `target`, wherever it is in `root`. */ -export const insertAfter = (root: Parents, target: Element, ...nodes: ElementContent[]) => - insertAt(1, root, target, nodes); - type Context = Pick; export const lineData = new AttachedPluginData<{ lines?: readonly ExpressiveCodeLine[] }>(() => ({})); diff --git a/packages/starlight-codeblocks/src/expressive-code/hidden-lines.ts b/packages/starlight-codeblocks/src/expressive-code/hidden-lines.ts index 3d348f5..eadf08e 100644 --- a/packages/starlight-codeblocks/src/expressive-code/hidden-lines.ts +++ b/packages/starlight-codeblocks/src/expressive-code/hidden-lines.ts @@ -72,6 +72,8 @@ export function pluginHiddenLines(): CodeblocksPlugin { } ${markerStyles(cssVar, `${PREFIX}-hidden-marker`, `${PREFIX}-hidden-marker span`, 'codeblocksHiddenLines', 'dashed')} .${PREFIX}-hidden-marker { + display: flex; + position: relative; width: 100%; padding: 0; border: 0; @@ -80,6 +82,13 @@ ${markerStyles(cssVar, `${PREFIX}-hidden-marker`, `${PREFIX}-hidden-marker span` font: inherit; text-align: left; } +.${PREFIX}-hidden-marker::before { + inset-inline: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}) ${cssVar('codePaddingInline')}; +} +/* Where the copy button always shows, it sits over the end of the first line. */ +@media (hover: none) { + .${PREFIX}-hidden-marker:first-child::before { inset-inline-end: calc(${cssVar('codePaddingInline')} + 2.5rem); } +} .${PREFIX}-hidden-marker span { display: inline-flex; align-items: center; diff --git a/packages/starlight-codeblocks/src/expressive-code/index.ts b/packages/starlight-codeblocks/src/expressive-code/index.ts index 4dbf7bc..2648600 100644 --- a/packages/starlight-codeblocks/src/expressive-code/index.ts +++ b/packages/starlight-codeblocks/src/expressive-code/index.ts @@ -94,7 +94,6 @@ export function createPlugins(options: ResolvedOptions, base?: string): Expressi ...(options.placeholders ? [pluginPlaceholders(options.placeholders)] : []), ...(options.mentions ? [pluginMentions()] : []), ...(options.permalinks ? [pluginPermalinks()] : []), - // Before hidden lines, so that its marker sits above a hidden lines marker on the same line. ...(options.skippedCode ? [pluginSkippedCode(options.skippedCode)] : []), ...(options.hiddenLines ? [pluginHiddenLines()] : []), ...(options.expandable ? [pluginExpandable(options.expandable)] : []), diff --git a/packages/starlight-codeblocks/src/expressive-code/notation.ts b/packages/starlight-codeblocks/src/expressive-code/notation.ts index a2833b2..63d3278 100644 --- a/packages/starlight-codeblocks/src/expressive-code/notation.ts +++ b/packages/starlight-codeblocks/src/expressive-code/notation.ts @@ -39,6 +39,8 @@ export interface Directive { text?: string; /** The line of the directive in the code block source, from 1. */ sourceLine: number; + /** Read from an alias, such as `// ...`, not written as a directive. */ + alias?: boolean; } const wordChar = /[\w$]/; @@ -276,7 +278,8 @@ export function parseLine( for (const { spec, directive } of result.items) { directives.push(directive); // In `[!code ++ error] text`, the text goes to the first directive that takes text. - if (spec.text) textOf ??= directive; + // A directive that goes on its own line is dropped from a line with code, so it takes no text there. + if (spec.text && !(spec.ownLine && hasCode)) textOf ??= directive; } removedBefore = true; } @@ -321,8 +324,8 @@ export interface LineAliases { } /** The name of the directive whose alias is all of `line`, or all of a comment that is all of `line`. */ -function aliasOf(line: string, syntaxes: CommentSyntax[], aliases: LineAliases) { - const text = line.trim(); +function aliasOf(line: string, syntaxes: CommentSyntax[], aliases: LineAliases, diff: boolean) { + const text = (diff ? line.replace(diffPrefix, '') : line).trim(); const bodies = syntaxes .filter(({ open, close }) => text.startsWith(open) && (!close || text.endsWith(close))) .map(({ open, close }) => text.slice(open.length, close ? -close.length : undefined).trim()); @@ -371,8 +374,9 @@ export function parseNotation( aliases: LineAliases = { comment: [], bare: [] }, ): ParsedLine[] { const parsed = lines.map((text, i): ParsedLine => { - const name = aliasOf(diff ? text.replace(diffPrefix, '') : text, syntaxes, aliases); - if (name) return { text, removed: false, directives: [{ name, count: 1, args: [], sourceLine: i + 1 }] }; + const name = aliasOf(text, syntaxes, aliases, diff); + if (name) + return { text, removed: false, directives: [{ name, count: 1, args: [], sourceLine: i + 1, alias: true }] }; if (syntaxes.length === 0) return { text, removed: false, directives: [] }; return parseLine(text, syntaxes, specs, report, i + 1, diff); }); @@ -410,7 +414,9 @@ const notationData = new AttachedPluginData<{ run: ExpressiveCodeLine[]; specs: DirectiveSpecs; diffIndent: Map; -}>(() => ({ directives: [], removed: [], output: [], run: [], specs: {}, diffIndent: new Map() })); + /** A diff that Expressive Code leaves as written, so its lines keep their `+` and `-`. */ + realDiff: boolean; +}>(() => ({ directives: [], removed: [], output: [], run: [], specs: {}, diffIndent: new Map(), realDiff: false })); /** The directives in a code block, optionally only those with one name, such as `code focus`. */ export function getDirectives(codeBlock: ExpressiveCodeBlock, name?: string): BlockDirective[] { @@ -516,12 +522,11 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl const { codeBlock, config } = context; const syntaxes = commentSyntaxFor(codeBlock.language, comments); const { specs, aliases } = specsOf(config.plugins, codeBlock.language); - const hasDirectives = syntaxes.length > 0 && /\[\\?!/.test(codeBlock.code); - const candidates = syntaxes.length > 0 ? [...aliases.bare, ...aliases.comment] : aliases.bare; - if (!hasDirectives && !candidates.some(([alias]) => codeBlock.code.includes(alias))) return; const lines = codeBlock.getLines(); // The text markers plugin reads the `useDiffSyntax` meta option only in `preprocessMetadata`. const diff = codeBlock.metaOptions.getBoolean('useDiffSyntax') ?? Boolean(codeBlock.props.useDiffSyntax); + const hasDirectives = syntaxes.length > 0 && /\[\\?!/.test(codeBlock.code); + if (!hasDirectives && !lines.some(({ text }) => aliasOf(text, syntaxes, aliases, diff))) return; const parsed = parseNotation( lines.map((line) => line.text), syntaxes, @@ -560,6 +565,7 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl data.removed = lines.filter((_, i) => parsed[i]?.removed); data.output = output; data.run = run; + data.realDiff = diff && !diffColumns(lines.map((line) => line.text)); if (code.length < lines.length) remapCollapse(codeBlock, lines, code); parsed.forEach(({ directives }, i) => { if (directives.length === 0) return; @@ -569,11 +575,14 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl const target = area.indexOf(line); for (const directive of directives) { if (area !== code && specs[directive.name]?.ownLine) { - warn( - context, - `\`[!${directive.name}]\` is not in the code, so it shows as a comment.`, - directive.sourceLine, - ); + // Output can hold `# ...` of its own. + if (!directive.alias) { + warn( + context, + `\`[!${directive.name}]\` is not in the code, so it shows as a comment.`, + directive.sourceLine, + ); + } continue; } data.directives.push({ ...directive, lines: area.slice(target, target + directive.count) }); @@ -605,13 +614,12 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl }, preprocessCode({ codeBlock }) { const syntaxes = commentSyntaxFor(codeBlock.language, comments); - const { removed, specs, diffIndent } = notationData.getOrCreateFor(codeBlock); + const { removed, specs, diffIndent, realDiff } = notationData.getOrCreateFor(codeBlock); for (const [line, columns] of diffIndent) line.editText(0, columns, ''); if (syntaxes.length > 0 && /\[\\?!/.test(codeBlock.code)) { - const diff = Boolean(codeBlock.props.useDiffSyntax); for (const line of codeBlock.getLines()) { // Other plugins can edit lines after the first parse, so parse the current text again. - const { text, removed: gone } = parseLine(line.text, syntaxes, specs, () => {}, 1, diff); + const { text, removed: gone } = parseLine(line.text, syntaxes, specs, () => {}, 1, realDiff); // The first parse kept this line, and blanking it would leave an empty line behind. if (gone && !removed.includes(line)) continue; if (text !== line.text) line.editText(0, line.text.length, text); @@ -626,7 +634,7 @@ export function pluginNotation({ comments }: NotationOptions = {}): CodeblocksPl }; } -const diffLine = /^(([+-](?![+-]))?\s*)(.*)$/; +export const diffLine = /^(([+-](?![+-]))?\s*)(.*)$/; /** * The columns that Expressive Code's diff syntax removes from a line of a block with `lines`, diff --git a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts index 34ec53b..357d634 100644 --- a/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts +++ b/packages/starlight-codeblocks/src/expressive-code/skipped-code.ts @@ -1,9 +1,9 @@ import { type ExpressiveCodeLine, PluginStyleSettings, type UnresolvedStyleValue } from '@expressive-code/core'; import { addClassName, h, select } from '@expressive-code/core/hast'; import { uiTexts } from '../translations.ts'; -import { type CodeblocksPlugin, lineElement } from './core.ts'; +import { type CodeblocksPlugin, isDecoration, lineElement } from './core.ts'; import { inlineMarkdown } from './inline-markdown.ts'; -import { getRenderedDirectives } from './notation.ts'; +import { diffLine, getRenderedDirectives } from './notation.ts'; import { markerColours, markerStyles, PREFIX } from './styles.ts'; export interface SkippedCodeStyleSettings { @@ -59,8 +59,9 @@ export function pluginSkippedCode({ ${markerStyles(cssVar, `${PREFIX}-skip-marker`, `${PREFIX}-skip-text`, 'codeblocksSkippedCode', 'dotted')} /* Not zero width or in a flex container: Chromium leaves either out of a manual selection. */ .${PREFIX}-skip-source { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: pre; } -.${PREFIX}-skip-marker { display: inline-flex; position: static; } +.${PREFIX}-skip-marker { display: inline-flex; } .${PREFIX}-skip-marker::before { inset-inline: ${cssVar('codePaddingInline')}; } +/* Where the copy button always shows, it sits over the end of the first line. */ @media (hover: none) { .ec-line:first-child .${PREFIX}-skip-marker::before { inset-inline-end: calc(${cssVar('codePaddingInline')} + 2.5rem); } } @@ -75,14 +76,20 @@ ${markerStyles(cssVar, `${PREFIX}-skip-marker`, `${PREFIX}-skip-text`, 'codebloc if (!code) continue; addClassName(el, `${PREFIX}-skip-line`); // A real diff keeps its `+` or `-` prefix in the text. - const indent = line.text.match(/^(?:[+-](?![+-]))?\s*/)?.[0] ?? ''; - code.children = [ + const indent = line.text.match(diffLine)?.[1] ?? ''; + // Other plugins' labels, such as a line state message, stay around the code. + const first = code.children.findIndex((node) => !isDecoration(node)); + const last = code.children.findLastIndex((node) => !isDecoration(node)); + if (first === -1) continue; + code.children.splice( + first, + last - first + 1, ...(indent ? [{ type: 'text' as const, value: indent }] : []), h('span', { class: `${PREFIX}-skip-source`, ariaHidden: 'true' }, line.text.slice(indent.length)), h('span', { class: `${PREFIX}-skip-marker` }, [ h('span', { class: `${PREFIX}-skip-text` }, text ? inlineMarkdown(text) : say('skippedCode.marker')), ]), - ]; + ); } }, }, diff --git a/packages/starlight-codeblocks/src/expressive-code/styles.ts b/packages/starlight-codeblocks/src/expressive-code/styles.ts index 76110c2..780a403 100644 --- a/packages/starlight-codeblocks/src/expressive-code/styles.ts +++ b/packages/starlight-codeblocks/src/expressive-code/styles.ts @@ -87,9 +87,7 @@ export const markerStyles = ( border: 'dashed' | 'dotted', ) => ` .${marker} { - display: flex; align-items: center; - position: relative; margin: 2px 0; color: ${cssVar('codeblocks.mutedForeground')}; user-select: none; @@ -99,14 +97,9 @@ export const markerStyles = ( content: ''; position: absolute; top: 50%; - inset-inline: calc(var(--scb-gutter, 0px) + ${cssVar('codePaddingInline')}) ${cssVar('codePaddingInline')}; border-top: 1px ${border} ${cssVar(`${group}.rule`)}; transform: translateY(-50%); } -/* Where the copy button always shows, it sits over the end of the first line. */ -@media (hover: none) { - .${marker}:first-child::before { inset-inline-end: calc(${cssVar('codePaddingInline')} + 2.5rem); } -} .${badge} { position: relative; z-index: 1; diff --git a/packages/starlight-codeblocks/test/skipped-code.test.ts b/packages/starlight-codeblocks/test/skipped-code.test.ts index a44f6c6..87b32a7 100644 --- a/packages/starlight-codeblocks/test/skipped-code.test.ts +++ b/packages/starlight-codeblocks/test/skipped-code.test.ts @@ -1,5 +1,8 @@ import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'; +import { fromHtml } from 'hast-util-from-html'; import { expect, test } from 'vitest'; +import { readTokens } from '../src/components/tokens.ts'; +import { markDecorations } from '../src/expressive-code/core.ts'; import { block, render } from './render.ts'; const skipLines = (html: string) => @@ -113,3 +116,37 @@ test('renders as without the feature when a block skips nothing, and leaves the 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 shown 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();'); +});