Code Snippet Extraction
On this page
An integration and component for loading code snippets into Astro pages.
Supports Bluehawk-annotated files (with // :snippet-start: / :snippet-end: markers)
and plain source file inclusion.
Installation
$ npm install astro-better-code-snippet-extractor @astrojs/prism
Setup
Register the integration
In astro.config.ts:
import { extractedCodeSnippets } from 'astro-better-code-snippet-extractor';
export default defineConfig({
integrations: [
extractedCodeSnippets(),
],
});
Put each source project in its own folder under extractedcode/, such as extractedcode/my-app/.
Use the component in MDX
import ExtractedCode from 'astro-better-code-snippet-extractor/ExtractedCode.astro';
<ExtractedCode src="my-app/login.snippet.loginExample.ts" lang="typescript" />
<ExtractedCode src="my-app/src/auth/login.ts" lang="typescript" title="login.ts" />
The first renders the loginExample snippet. The second renders the whole file.
Integration options
| Option | Type | Default | Description |
|---|---|---|---|
sourceDir | string | 'extractedcode' | Directory of annotated source projects; each subdirectory is processed separately |
outputDir | string | 'src/generated-code-snippets' | Where to write snippets and whole-file copies |
ignore | string[] | node_modules, vendor, lockfiles, and similar | Patterns passed to Bluehawk’s --ignore |
plugin | string | none | Bluehawk plugin path, relative to the project root |
state | string | none | Bluehawk state passed to --state, so snippets and whole files match a published state |
For each project, the integration runs bluehawk snip to write the snippets and bluehawk copy to write a copy of the whole project with Bluehawk markup removed. Both land in outputDir. The integration hashes sourceDir and skips this when nothing changed since the last run. It also reruns after a package upgrade or a change to its options, so output restored from a cache built another way gets regenerated. When something did change, it regenerates every project in parallel, one per CPU. Bluehawk ships as a dependency, so no npx download or startup is involved.
ExtractedCode props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | (required) | Path relative to sourceDir. A path containing .snippet. names a snippet. Any other path renders a whole file |
lang | string | plaintext | Language for syntax highlighting |
title | string | — | Filename label shown above the code block |
snippetRoot | string | src/generated-code-snippets | Where to read snippets and whole files. Match the integration’s outputDir |
sourceRoot | string | extractedcode | Where to read whole files the integration ignored, such as package.json |
Whole files render from the integration’s copy, so nested snippet markers and other Bluehawk markup never show up on the page.
Bluehawk annotations
Annotate source files with Bluehawk markers:
// :snippet-start: loginExample
async function login(username: string, password: string) {
const response = await fetch('/api/login', {
method: 'POST',
body: JSON.stringify({ username, password }),
});
return response.json();
}
// :snippet-end:
The integration runs Bluehawk at build time to extract annotated regions and strip the markup from whole files.
The ExtractedCode component then renders the result with syntax highlighting.