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.
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:
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
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-smartypantsturns--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"
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"
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: '$ ',
})