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

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.

Current version: 0.3.1 --npm

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

OptionTypeDefaultDescription
sourceDirstring'extractedcode'Directory of annotated source projects; each subdirectory is processed separately
outputDirstring'src/generated-code-snippets'Where to write snippets and whole-file copies
ignorestring[]node_modules, vendor, lockfiles, and similarPatterns passed to Bluehawk’s --ignore
pluginstringnoneBluehawk plugin path, relative to the project root
statestringnoneBluehawk 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

PropTypeDefaultDescription
srcstring(required)Path relative to sourceDir. A path containing .snippet. names a snippet. Any other path renders a whole file
langstringplaintextLanguage for syntax highlighting
titlestring—Filename label shown above the code block
snippetRootstringsrc/generated-code-snippetsWhere to read snippets and whole files. Match the integration’s outputDir
sourceRootstringextractedcodeWhere 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.