# starlight-codeblocks

> A Starlight plugin that adds focus, line states, annotations, API auto-linking and 22 more features to the code blocks of a site.

Each page below links to its Markdown version. Code blocks keep their fence lines, so the attributes and directives are as an author writes them. [llms-full.txt](https://ewels.github.io/starlight-codeblocks/llms-full.txt) has every page in one file.

## Start here

- [Introduction](https://ewels.github.io/starlight-codeblocks/index.md): A Starlight plugin that adds focus, line states, annotations, API auto-linking and 22 more features to the code blocks of a site.
- [Getting started](https://ewels.github.io/starlight-codeblocks/getting-started.md): Install starlight-codeblocks and add it to a Starlight site.
- [Configuration](https://ewels.github.io/starlight-codeblocks/configuration.md): Turn features off, change their settings and change their colours with one options object.
- [Comment notation](https://ewels.github.io/starlight-codeblocks/comment-notation.md): Mark lines with directives in code comments. The plugin applies each directive and removes it from the code that readers see and copy.
- [Use with an AI agent](https://ewels.github.io/starlight-codeblocks/agent-skill.md): Install the starlight-codeblocks agent skill, so an AI coding agent knows each feature, its syntax and when to use it.

## Explain code

- [Annotations](https://ewels.github.io/starlight-codeblocks/features/annotations.md): Add numbered markers to lines. Each marker opens a note in a popover, so the code stays clean until a reader asks.
- [Side annotations](https://ewels.github.io/starlight-codeblocks/features/side-annotations.md): Show the notes of an annotated block in a column beside the code, so readers see every note next to its line.
- [Footnotes](https://ewels.github.io/starlight-codeblocks/features/footnotes.md): Add numbered badges to lines, with the notes in a list under the block, where readers see them all at once.
- [Inline callouts](https://ewels.github.io/starlight-codeblocks/features/inline-callouts.md): Put a short note in a bubble above a line, with an arrow that points at the word it explains.
- [Scrollycoding](https://ewels.github.io/starlight-codeblocks/features/scrollycoding.md): Explain a code block in prose steps that scroll past it, while the block stays in view and focuses the lines of each step.
- [Code walkthrough](https://ewels.github.io/starlight-codeblocks/features/code-walkthrough.md): Step through versions of one code block, and watch the code move from each version to the next, so readers see what changed.

## Draw attention

- [Focus](https://ewels.github.io/starlight-codeblocks/features/focus.md): Blur the lines outside a range, so that readers look at the lines that you name first.
- [Line states](https://ewels.github.io/starlight-codeblocks/features/line-states.md): Tint lines as errors, warnings, notes or successes, with an optional message after the code, like the diagnostics in a code editor.
- [Code mentions](https://ewels.github.io/starlight-codeblocks/features/code-mentions.md): Link a phrase in the prose to lines of the code block below it, so that readers see which lines the text is about.

## Make code easier to read

- [Hidden lines](https://ewels.github.io/starlight-codeblocks/features/hidden-lines.md): Hide the imports and set-up that readers need to run an example but not to understand it.
- [Expandable blocks](https://ewels.github.io/starlight-codeblocks/features/expandable-blocks.md): Show the first lines of a long block, with a fade and a button to reveal the rest.
- [Visible whitespace](https://ewels.github.io/starlight-codeblocks/features/visible-whitespace.md): Show spaces and tabs as faint glyphs, for the blocks where indentation changes the meaning of the code.
- [Colourised brackets](https://ewels.github.io/starlight-codeblocks/features/colourised-brackets.md): Colour matching brackets by nesting depth, so a dense line of code stays readable.
- [Colour swatches](https://ewels.github.io/starlight-codeblocks/features/colour-swatches.md): Show a small swatch of each CSS colour next to its value, so readers see the colour without a colour picker.
- [File icons](https://ewels.github.io/starlight-codeblocks/features/file-icons.md): Show the icon of the file type before the title of a code block, with the icons of the Starlight file tree or a coloured icon set.
- [Inline code highlighting](https://ewels.github.io/starlight-codeblocks/features/inline-code-highlighting.md): Give inline code in the prose the syntax colours of the code blocks, from a language suffix or a default language for the site.
- [Word-level diff](https://ewels.github.io/starlight-codeblocks/features/word-level-diff.md): Highlight the words that changed inside each line of a diff, so readers find a small edit in a long line.

## Link code

- [Code links](https://ewels.github.io/starlight-codeblocks/features/code-links.md): Turn text in code into a link with a card that describes it, from a directive in the comment above.
- [API auto-linking](https://ewels.github.io/starlight-codeblocks/features/api-auto-linking.md): Link the names in code examples to their reference pages, with a card that shows the signature and a summary.
- [Line permalinks](https://ewels.github.io/starlight-codeblocks/features/line-permalinks.md): Give a code block line numbers that link to each line, so readers can share a link to the exact lines they mean. Shift-click to select multiple lines.

## Adapt to the reader

- [Code tabs](https://ewels.github.io/starlight-codeblocks/features/code-tabs.md): Show several code blocks as one, with editor tabs in the title bar, such as the files of a project or the commands for each package manager.
- [Fill-in placeholders](https://ewels.github.io/starlight-codeblocks/features/fill-in-placeholders.md): Turn placeholders such as YOUR_TOKEN into fields, so readers type their own values into every block and the copied code.

## Copy and run

- [Smart shell copy](https://ewels.github.io/starlight-codeblocks/features/smart-shell-copy.md): Add a Copy commands button to terminal blocks, which copies the commands without the prompts or the output.
- [Open in playground](https://ewels.github.io/starlight-codeblocks/features/open-in-playground.md): Add a title bar button that opens the example in an online playground, with the code already filled in.
- [Run code](https://ewels.github.io/starlight-codeblocks/features/run-code.md): Add a Run code button that runs the example in the browser and shows the output under the block.

## Extend

- [Write an API link adapter](https://ewels.github.io/starlight-codeblocks/extend/write-an-api-link-adapter.md): Add API auto-linking for another language or library, with an adapter that finds names in code and resolves them to reference pages.
- [Add a playground](https://ewels.github.io/starlight-codeblocks/extend/add-a-playground.md): Add a custom playground to the site, for any online playground that takes code in its URL or in a form post.
- [Add a runtime](https://ewels.github.io/starlight-codeblocks/extend/add-a-runtime.md): Add a runtime for another language, so that the Run code button can run its code blocks in the browser.

## Reference

- [Options](https://ewels.github.io/starlight-codeblocks/reference/options.md): Every option of codeblocks() and pluginCodeblocks(), with its type and default.
- [Attributes](https://ewels.github.io/starlight-codeblocks/reference/attributes.md): Every attribute that the plugin reads on the first line of a code block, with an example of each.
- [Directives](https://ewels.github.io/starlight-codeblocks/reference/directives.md): Every directive that the plugin reads in code comments, with an example of each.
- [Style settings](https://ewels.github.io/starlight-codeblocks/reference/style-settings.md): Every style setting of the plugin, with its defaults for dark and light themes.
- [Expressive Code plugins](https://ewels.github.io/starlight-codeblocks/reference/expressive-code-plugins.md): The Expressive Code plugins that the package exports, for sites that configure Expressive Code themselves.
- [Plugin compatibility](https://ewels.github.io/starlight-codeblocks/reference/plugin-compatibility.md): Configure the plugin next to other Starlight plugins, themes, Expressive Code plugins and Markdown processors.
- [Themes](https://ewels.github.io/starlight-codeblocks/reference/themes.md): See the features in eight Expressive Code themes, and learn how the plugin takes its colours from the theme of your site.
- [Accessibility](https://ewels.github.io/starlight-codeblocks/reference/accessibility.md): What each feature does for keyboard users, screen reader users and readers who ask for reduced motion, and the contrast that the default styles meet.