---
title: "Skipped code"
description: "Show a marker where a code block leaves out code, so readers know the file has more lines there."
url: "https://ewels.github.io/starlight-codeblocks/features/skipped-code/"
markdown: "https://ewels.github.io/starlight-codeblocks/features/skipped-code.md"
section: "Make code easier to read"
site: "starlight-codeblocks documentation"
context: "This page is from the documentation of starlight-codeblocks. A plugin for Starlight and Astro that adds focus, line states, annotations, API auto-linking and 24 more features to the code blocks of a site."
index: "https://ewels.github.io/starlight-codeblocks/llms.txt"
---

# Skipped code

> Show a marker where a code block leaves out code, so readers know the file has more lines there.

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

````md
```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

| 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

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.

:::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:

````md
```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:

```js title="astro.config.mjs"
codeblocks({
  skippedCode: {
    // [!callout /commentAliases/] `// …` as well as `// ...`, and no comment aliases in Python.
    commentAliases: { '*': ['...', '…'], python: [] },
    // [!callout /bareAliases/] `...` 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

### 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:

````md
```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

A marker on the first line shows that the example starts in the middle of a file:

````md
```py title="report.py"
# [!code skip] Not shown: 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:

````md
```yaml title="docker-compose.yml"
services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  # [!code skip] Not shown: The database and cache services
volumes:
  data:
```
````

### Link to lines after a marker

The marker is a line of the block, so it has a line number. With [line permalinks](https://ewels.github.io/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:

````md
```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:
  - 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.
- 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.
- Screen readers:
  - Screen readers read the text of the marker in its place among the lines, and not the comment.
- Print:
  - Markers print.

## Options

### `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`

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`

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.

- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration/): Learn how to set options for the whole site, or for a single code block.

## 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 `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](https://ewels.github.io/starlight-codeblocks/features/hidden-lines/): keep the lines in the block and the copied code, behind a marker that readers can open.
- [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks/): show a full file, cut to its first lines until the reader asks for the rest.
- [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation/): the directive syntax that `[!code skip]` uses.
