Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .agents/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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

Expand Down
Binary file added .github/assets/readme/skipped-code.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
21 changes: 20 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<img src="https://raw.githubusercontent.com/ewels/starlight-codeblocks/main/.github/assets/logotype.svg" width="800" alt="starlight-codeblocks">
</h1>

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/).

Expand Down Expand Up @@ -244,6 +244,25 @@ Hide the imports and set-up that readers need to run an example but not to under

</details>

<details>
<summary>Skipped code</summary>

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] Not shown: Read the users from the database
});
```
````

<img src="https://raw.githubusercontent.com/ewels/starlight-codeblocks/main/.github/assets/readme/skipped-code.png" alt="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/)

</details>

<details>
<summary>Expandable blocks</summary>

Expand Down
14 changes: 7 additions & 7 deletions docs/e2e/carousel.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand All @@ -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');
});

Expand All @@ -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)));

Expand All @@ -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');
});
Expand Down Expand Up @@ -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/');
Expand Down
58 changes: 58 additions & 0 deletions docs/e2e/skipped-code.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
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 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(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();
});
1 change: 1 addition & 0 deletions docs/src/components/FeatureCarousel.astro
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ const icons: Record<string, string> = {
'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,
Expand Down
4 changes: 3 additions & 1 deletion docs/src/content/docs/comment-notation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 `. 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, and the comment aliases of [skipped code](/starlight-codeblocks/features/skipped-code/). The built-in map:

<CommentSyntaxTable />

Expand Down
1 change: 1 addition & 0 deletions docs/src/content/docs/features/code-walkthrough.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 or a hidden lines marker changes without the animation. The animation does not have the height of these rows.

## Options

Expand Down
Loading
Loading