@devrelkit/remark-include-code

A remark plugin that includes code from external files into markdown / MDX, with named-region slicing and line-highlight passthrough.

The classic problem: code samples in docs drift out of sync with reality because they live as plain text inside the docs. This plugin lets you keep examples as real source files that get tested in CI, then transclude them into your docs at build time.

Install

pnpm add -D @devrelkit/remark-include-code
# or
npm install --save-dev @devrelkit/remark-include-code

Usage

import { remark } from "remark";
import remarkIncludeCode from "@devrelkit/remark-include-code";

const file = await remark()
  .use(remarkIncludeCode, {
    /* options */
  })
  .process(markdown);

In your markdown / MDX, replace inline code with a file= directive on the fence:

```ts file=./examples/create-account.ts#region=create
```

The plugin reads ./examples/create-account.ts (relative to the markdown file), extracts the create region, and replaces the codeblock body. The fence keeps its language tag, so downstream highlighters work normally.

Region markers

Regions in source files use a comment style that's neutral across most languages:

// #region create
const account = createAccount({ payer, lamports });
// #endregion create

# #region create
account = Account(payer=payer, lamports=1_000_000)
# #endregion create

The plugin picks the comment token (// or #) automatically based on the codeblock's language tag.

Supported languages out of the box:

• // — ts, tsx, typescript, js, jsx, javascript, rust, rs, c, cpp, go, java, swift, kotlin, scala, dart
• # — py, python, sh, bash, zsh, ruby, yaml, toml, r, perl

Multiple regions with the same name in one file are concatenated (separated by a blank line) — useful for stitching non-contiguous pieces into one example.

The common leading indent of the region body is stripped, so a region defined inside an indented block still renders flush-left.

Line highlighting

Add highlight= to mark lines for visual emphasis:

```ts file=./examples/create-account.ts#region=create highlight=2-5,10
```

By default the ranges are appended to the codeblock meta as {2-5,10}, which is the convention used by Shiki, rehype-pretty-code, VitePress, and Astro Starlight. Configure highlightStyle for other renderers (see Options).

Whole-file include

Drop the #region=... to include the whole file:

```ts file=./examples/full-script.ts
```

Other meta fields pass through

Anything other than file= and highlight= is preserved on the meta string:

```ts title="Kit" file=./examples/foo.ts#region=create
```

→ output keeps title="Kit" so renderers like CodeHike's <CodeTabs> see what they expect.

Options

interface PluginOptions {
  rootDir?: string;
  highlightStyle?:
    | "fence-meta"
    | "codehike"
    | ((ctx: HighlightContext) => HighlightResult);
}

rootDir

Resolution root for file= paths. Defaults to the directory of the markdown file being processed (recommended). Set this if you want to centralise examples in one location and reference them from anywhere with the same relative path.

highlightStyle

How highlight= ranges land in the output:

• "fence-meta" (default): appends {2-5,10} to the codeblock meta string. Compatible with Shiki, rehype-pretty-code, VitePress, Astro Starlight, and most modern markdown highlighters.
• "codehike": injects // !mark(N:M) (or # !mark(N:M) for hash-comment languages) above each highlighted range, so CodeHike's mark annotation handler picks them up.
• function: receives the slice + ranges + lang + meta, returns the final code + meta. Use this for any other renderer or custom annotation format.

import remarkIncludeCode, { type HighlightContext } from "@devrelkit/remark-include-code";

remark().use(remarkIncludeCode, {
  highlightStyle: (ctx: HighlightContext) => ({
    code: ctx.code,
    meta: `${ctx.meta} data-lines=${JSON.stringify(ctx.ranges)}`,
  }),
});

Errors

The plugin throws (rather than silently producing wrong output) when:

• file= path doesn't resolve to a readable file
• #region=... doesn't exist in the source
• highlight= range is malformed (abc, 5-2, etc.)

All wrap as IncludeError with the markdown file path included, so build failures point you at the broken doc.

Why a remark plugin?

remark is the markdown half of the unified ecosystem. It parses markdown into an AST (mdast), runs plugins to transform that tree, then serialises back. MDX, Fumadocs, Docusaurus, Next.js, Astro, and most modern markdown stacks compose on top of it — so a remark plugin slots into all of them via a one-line .use(...) registration.

License

MIT