Skipped code
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.
Readers see
const app = express();
app.get('/users', async (req, res) => { Not shown: 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 not shownYou write
```js title="routes.js"const app = express();
app.get('/users', async (req, res) => { // [!code skip] Not shown: 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 each marker as a comment, such as // Not shown: Read the users from the database.
Syntax
Section titled “Syntax”| Syntax | Where |
|---|---|
[!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. 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
Section titled “Aliases”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.
This JSON block shows two markers:
{ "name": "my-site", "scripts": { "dev": "astro dev", Code not shown }, Code not shown}```json title="package.json"{ "name": "my-site", "scripts": { "dev": "astro dev", ... }, ...}```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. The defaults are commentAliases: { '*': ['...'] } and bareAliases: { json: ['...'] }. Your entries merge over them, and [] turns aliases off for a language:
codeblocks({ skippedCode: {// … as well as // ..., and no comment aliases in Python. commentAliases: { '*': ['...', '…'], python: [] },... with no comment in YAML. JSON keeps its default. bareAliases: { yaml: ['...'] }, },});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
Section titled “Examples”Skip code without text
Section titled “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 class Cache<T> { private entries = new Map<string, T>();
Code not shown
get(key: string): T | undefined { return this.entries.get(key); } Code not shown}```ts title="cache.ts"export class Cache<T> { private entries = new Map<string, T>();
// [!code skip]
get(key: string): T | undefined { return this.entries.get(key); } // [!code skip]}```Skip the start of a file
Section titled “Skip the start of a file”A marker on the first line shows that the example starts in the middle of a file:
Not shown: Imports and settingsdef summarise(rows): totals = {} for row in rows: totals[row["status"]] = totals.get(row["status"], 0) + 1 return totals```py title="report.py"# [!code skip] Not shown: Imports and settingsdef 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
Section titled “Skip a section of a configuration file”YAML uses # comments. For JSON, use jsonc, because JSON has no comments:
services: web: image: nginx:1.27 ports: - "8080:80" Not shown: The database and cache servicesvolumes: data:```yaml title="docker-compose.yml"services: web: image: nginx:1.27 ports: - "8080:80" # [!code skip] Not shown: The database and cache servicesvolumes: data:```Link to lines after a marker
Section titled “Link to lines after a marker”The marker is a line of the block, so it has a line number. With 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:
```js title="routes.js" id="routes"const app = express();// [!code skip] Not shown: Middleware and settingsapp.get('/users', async (req, res) => { const users = await db.users.findAll(); res.json(users);});```Behaviour
Section titled “Behaviour”- The marker:
- 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 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.
- The marker is a line of the block. It has a line number, and line ranges such as
- Copy and selection:
- 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.
- The copy button and a manual selection copy the marker as a comment, such as
- Screen readers:
- Screen readers read the text of the marker in its place among the lines, and not the comment.
- Print:
- Markers print.
Options
Section titled “Options”skippedCode
Section titled “skippedCode”Shows a marker in place of code that a block leaves out. Set it to false to turn the feature off. [!code skip] then stays in the code as written.
- Type
false | object- Default
- On
skippedCode.commentAliases
Section titled “skippedCode.commentAliases”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.
- Type
Record<string, string[]>- Default
{'*':['...']}
skippedCode.bareAliases
Section titled “skippedCode.bareAliases”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.
- Type
Record<string, string[]>- Default
{'json':['...']}
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
Section titled “Limitations”- 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
startLineNumberattribute 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
Section titled “Related”- Hidden lines: keep the lines in the block and the copied code, behind a marker that readers can open.
- Expandable blocks: show a full file, cut to its first lines until the reader asks for the rest.
- Comment notation: the directive syntax that
[!code skip]uses.