For AI agents: The complete documentation index is available at /llms.txt. A markdown version of this page is available at /build-tools/code-blocks.md.

Code Snippets

On this page

Remark and rehype plugins, plus Sätteri equivalents, that enhance code blocks in Astro MDX files. Adds a copy-to-clipboard button, syntax highlighting via Prism, and a meta string mini-language for titles, line highlights, collapsible sections, and diff overlays. Also formats shell session blocks with distinct prompt styling.

Current version: 0.2.5 --npm

Installation

$ npm install astro-better-code-blocks @astrojs/prism prismjs

Import the CSS in your global stylesheet:

@import "astro-better-code-blocks/style.css";

Setup

Configure the plugins

In astro.config.ts:

astro.config.ts
import { defineConfig } from 'astro/config';
import { rehypeCodeBlocks, remarkShellSession } from 'astro-better-code-blocks';

export default defineConfig({
  markdown: {
    syntaxHighlight: false,
    remarkPlugins: [remarkShellSession],
    rehypePlugins: [rehypeCodeBlocks],
  },
});

Import the CSS

In your root layout or global stylesheet:

@import "astro-better-code-blocks/style.css";

Use with Sätteri

Sätteri parses and compiles Markdown and MDX in Rust, which makes builds of large sites much faster. The astro-better-code-blocks/satteri entry point exports Sätteri plugins that produce the same HTML as the unified ones:

$ npm install @astrojs/markdown-satteri
astro.config.ts
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { satteri } from '@astrojs/markdown-satteri';
import { codeBlocks, shellSession } from 'astro-better-code-blocks/satteri';

const processor = satteri({
  mdastPlugins: [shellSession()],
  hastPlugins: [codeBlocks()],
});

export default defineConfig({
  markdown: { syntaxHighlight: false, processor },
  integrations: [mdx({ syntaxHighlight: false, processor })],
});

shellSession takes the same options as remarkShellSession, and codeBlocks takes the same options as rehypeCodeBlocks. The unified plugins stay at the package root, so existing configs keep working without changes.

Sätteri itself differs from the unified pipeline in two ways that can change your output when you switch:

  • With smart punctuation on, Sätteri turns -- into an en dash and --- into an em dash. remark-smartypants turns -- into an em dash.
  • Sätteri follows CommonMark when deciding whether a list is tight, so a few lists that micromark rendered as loose (<li><p>) render tight.

Meta string features

All features are activated by keywords or patterns in the opening code fence. They can be combined freely on the same block.

Title tab

title="filename" renders a filename tab above the code block.

```ts title="src/lib/auth.ts"
src/lib/auth.ts
export async function verifyToken(token: string) {
  const payload = await decode(token);
  return payload.sub;
}

Line highlighting

{lines} highlights specific lines with a yellow tint and a left accent bar. Accepts individual lines and ranges separated by commas.

```ts {2,6-8}
import { defineConfig } from 'astro/config';import { rehypeCodeBlocks, remarkShellSession } from 'astro-better-code-blocks';export default defineConfig({  markdown: {    remarkPlugins: [remarkShellSession],    rehypePlugins: [rehypeCodeBlocks],  },});

Collapsible sections

[lines] hides a range of lines behind an expandable toggle. Use this to keep examples focused while still making the full code accessible.

```ts [4-8]
import { defineConfig } from 'astro/config';import { rehypeCodeBlocks, remarkShellSession } from 'astro-better-code-blocks';5 hidden linesexport default defineConfig({  markdown: {    remarkPlugins: [remarkShellSession],    rehypePlugins: [rehypeCodeBlocks],    syntaxHighlight: false,  },  integrations: [],});

Diff mode

diff colors lines that start with + green and lines that start with - red. diff adds the color overlay on top of any language.

```ts diff
-import { oldHelper } from './utils';+import { newHelper } from './helpers';export function processData(input: string) {-  return oldHelper(input);+  return newHelper(input);}

Escape (MDX-safe blocks)

escape renders the block using JSX grammar so that MDX component tags like <Details> appear as literal text instead of being executed by the MDX compiler. Use this whenever you’re documenting MDX component usage inside an MDX file.

````mdx escape
import Details from 'astro-better-details/Details.astro';

<Details title="Click to expand">
  This content is hidden by default and revealed when clicked.
</Details>

Without escape, the <Details> tag above would render as a live component rather than source code.

Combining features

All meta keywords compose freely on the same fence:

```ts {2} [5-8] title="astro.config.ts"
astro.config.ts
import { defineConfig } from 'astro/config';import { rehypeCodeBlocks, remarkShellSession } from 'astro-better-code-blocks';export default defineConfig({4 hidden lines  markdown: {    remarkPlugins: [remarkShellSession],    rehypePlugins: [rehypeCodeBlocks],    syntaxHighlight: false,  },});

Line 2 is highlighted, lines 5-8 are collapsible, and a title tab appears above.

Shell session

shell-session blocks are processed by remarkShellSession before syntax highlighting. Each command gets $ prepended automatically, so you can write clean commands without repeating the prompt on every line.

The prompt and the space after it are excluded from the copy button — clicking copy gives you the raw commands.

$ npm install astro-better-code-blocks
$ npx astro dev

Multi-line commands

Lines that continue a command don’t get a prompt: lines after a trailing \, &&, ||, or |, lines inside a multi-line single- or double-quoted string, and the body of a heredoc.

$ npm install \
    astro-better-code-blocks \
    @astrojs/prism prismjs && \
npx astro dev

Mixed commands and output

If any line in a block already starts with $ , the block is left exactly as written: prompted lines render as commands and everything else renders as output. The copy button copies only the commands, not the output.

$ git status
$ On branch main
$ nothing to commit, working tree clean
$ git log --oneline -3
$ 1dc6d53 Update llms-for-docs and actions
$ 62ba842 migrate php quickstart to bluehawk
$ 6d4605 migrate laravel quickstart to bluehawk

Plugin options

The Sätteri plugins codeBlocks and shellSession take the same options as their unified counterparts below.

rehypeCodeBlocks

rehypeCodeBlocks({
  // Languages to skip entirely -- no highlighting, no copy button wrapper.
  // Default: ['mermaid']
  excludeLangs: ['mermaid'],

  // Inject a copy-to-clipboard button into every code block.
  // Default: true
  copyButton: true,

  // Position of the title tab when title="..." is present.
  // Default: { position: 'top' }
  title: { position: 'top' },
})

remarkShellSession

remarkShellSession({
  // Prompt string prepended to lines that have no existing prompt.
  // Default: '$ '
  prompt: '$ ',
})