Skip to content

skipped-code: add [!code skip], a marker for code that a block leaves out - #39

Merged
ewels merged 11 commits into
mainfrom
skipped-code
Nov 18, 2026
Merged

ewels merged 11 commits into
mainfrom
skipped-code

Conversation

@ewels

@ewels ewels commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Adds the "code skipped" marker from #28. It shows where a code block leaves out code, in place of a // ... comment that readers can mistake for code. Authors write the [!code skip] directive, with optional text. A site can also read its existing // ... comments as markers, with skippedCode.aliases: ['...']. This is off by default, because it changes existing pages.

app.get('/users', async (req, res) => {
  // [!code skip] Not shown: Read the users from the database
});
// [!code skip]

Skipped code in the light theme
Skipped code in the dark theme

Changes

  • New feature: skipped code, [!code skip]
    • The marker takes the place of the directive line, at its indentation: a dotted rule with the text in a badge. A dotted rule tells it apart from the dashed hidden lines marker, which readers can open.
    • The text after the directive goes in the badge, with inline Markdown. Without text, the badge reads "Code not shown", translated into all 17 bundled languages.
    • At the end of a line, the marker goes above that line. On its own line at the end of the block, it goes after the last line of code, also after [!output] or [!run] lines. Several markers there keep their source order.
    • In a diff block, a directive line with a + or - prefix works, and the marker takes the indentation that readers see.
    • A marker between hidden lines hides and shows with them. A marker above a hidden run stays visible.
    • The marker is static HTML, with no client module. The copied code and a manual selection leave it out.
    • skippedCode: false turns the feature off.
  • Aliases: ... lines, opt-in
    • skippedCode.aliases defaults to []. With ['...'], a comment that holds only ... (// ..., # ..., /* ... */, <!-- ... -->) is the same as [!code skip].
    • In JSON, which has no comments, ... alone on its line is the same.
    • A bare ... in a language with comments stays code: it is the ellipsis in Python and the end of a document in YAML. A comment with more text, such as // ... and so on, also stays, which keeps a // ... as code in one block.
    • Aliases take no text. For a marker with text, authors use [!code skip] text.
    • The docs site sets ['...'], for the JSON example.
  • Comment notation
    • A directive spec can set endOfBlock. A directive line at the end of the block then applies after the last line, in place of the warning "has no line below it". Only [!code skip] sets it.
    • A directive spec can set aliases, read as described above.
    • hasNoComments() in comments.ts tells JSON apart, unless the site gives it a comment syntax. commentSyntaxFor() is unchanged. A language set to [] in notation.comments reads no directives and no aliases.
    • core.ts gets insertAfter() next to insertBefore().
  • Styles
    • Hidden lines and skipped code share their marker colours and CSS, through markerColours and markerStyles in styles.ts. Each keeps its own settings group.
  • Docs
    • New feature page, with examples with and without text, in JSON, at the start of a file and in YAML. A section on the aliases has a caution about what they change on existing pages.
    • Sidebar, home carousel, plugins reference, comment notation options, README section and image, skill, DECISIONS.md and the changelog are updated. The feature count is now 29.
    • The code walkthrough page and the skill say that a step with a callout, a hidden lines marker or a skipped code marker changes without the animation.

Design notes

  • The aliases are opt-in
    • The // ... lines leave the code, so every line range after them, such as {4} or ins={4}, counts different lines. Their walkthrough steps also stop animating. On by default, that changes pages that never asked for the feature.
    • No per-block switch: with the aliases on, a comment with more text keeps // ... as code.
  • The dotted rule stays faint
    • The badge text says what the marker is, and meets 4.5:1. The rule is decoration, as faint as the hidden lines rule.
  • No fence attribute, such as skip={range}
    • A range names lines, not the gaps between them, and cannot name the end of the block. The ... alias covers JSON instead.
  • Line numbers do not jump over the marker
    • That would need :N as a count of skipped lines, where every other directive reads :N as the lines it applies to.

Checks

  • pnpm lint, pnpm lint:docs, pnpm test (597 unit tests and the script tests) and pnpm docs:build pass with no warnings.
  • Playwright: the skipped code, hidden lines, code walkthrough and carousel specs pass. The skipped code spec covers the marker indentation and height, and a manual selection.
  • Unit tests cover the opt-in default, hidden runs, diff prefixes, the end-of-block order and output lines.
  • Screenshots checked in the light and dark themes.

Closes #28

🤖 Generated with Claude Code

ewels and others added 11 commits November 17, 2026 12:50
…es 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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
…er texts with "Not shown: "

The alias note goes in a tip aside. The README image is regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nts 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 <noreply@anthropic.com>
…n 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 <noreply@anthropic.com>
…nly when a site uses them

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n section

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nguage

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 <noreply@anthropic.com>
…to the skipped code page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d 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 <noreply@anthropic.com>
@ewels
ewels merged commit 8c6f14e into main Nov 18, 2026
7 checks passed
@ewels
ewels deleted the skipped-code branch November 18, 2026 07:56
@ewels ewels mentioned this pull request Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature request: render ellipsis nicely

1 participant