Snippets

The <Snippet> component embeds reusable MDX fragments from the top-level snippets/ directory. Write a shared block once, then reference it from as many pages as you need. components/Snippet.tsx reads the file on the server and renders it through the same remark and rehype pipeline as the page around it.

Quick Start

Reference a snippet by its path, without the extension.

ℹ️ NOTE This is a reusable snippet from snippets/install-note.mdx. Edit the file once and every page that embeds it picks up the change.

npm install @your-org/sdk

<Snippet path="install-note" />

Adding Options

resolveSnippetPath normalizes the path before it touches disk, so several spellings land on the same file. Spell out .mdx when you prefer the full filename, start with a slash if that reads better to you, or use Windows-style backslashes; the resolver strips leading slashes and rewrites every backslash to a forward slash. Percent-encoding is decoded first, so install%2Dnote gets there too.

ℹ️ NOTE This is a reusable snippet from snippets/install-note.mdx. Edit the file once and every page that embeds it picks up the change.

npm install @your-org/sdk

ℹ️ NOTE This is a reusable snippet from snippets/install-note.mdx. Edit the file once and every page that embeds it picks up the change.

npm install @your-org/sdk

ℹ️ NOTE This is a reusable snippet from snippets/install-note.mdx. Edit the file once and every page that embeds it picks up the change.

npm install @your-org/sdk

<Snippet path="install-note.mdx" />
 
<Snippet path="/install-note" />
 
<Snippet path="\install-note" />

A .md extension is honored as written, and the match is case-insensitive, so install-note.MDX reads that exact filename. Anything else gets .mdx appended to the last segment. Nested folders work the same way: legal/privacy-notice resolves to snippets/legal/privacy-notice.mdx.

Advanced

Paths stay confined to snippets/. The examples below deliberately point outside that directory, so each one renders an inline warning instead of reading the file or breaking the build. The second form arrives percent-encoded, and because the resolver decodes before it validates, it is rejected exactly like the plain one.

<Snippet path="../hidden-note" />
 
<Snippet path="%2e%2e/hidden-note" />

A .. or . segment anywhere in the path, a null byte, an empty string, and a malformed percent-escape all produce that same "Invalid snippet path." banner. A path that stays inside snippets/ but names a file that isn't there reports "File not found in snippets directory." instead, and any other read failure reports the underlying error code, so the three cases stay easy to tell apart in review.

What runs inside a snippet

A snippet is not a plain text include. It compiles through MDXRemote with the same plugin stack the page uses, so a fragment can carry GitHub-flavored Markdown, GitHub alerts, KaTeX math, {{vars.NAME}} substitution from owndocs.config.json, and any component in the shared map from lib/mdx-components-server.tsx. That map includes Snippet itself, so one fragment can embed another.

Headings inside a snippet get slugs and a prepended anchor link like any other heading. Reuse a snippet with headings twice on one page and both copies claim the same ID, so keep headings out of fragments you plan to repeat.

Rendering happens on the server, so the fragment's HTML is in the initial response rather than fetched later. The page's own search record is built from its raw MDX in lib/search-index.ts, which sees the <Snippet> tag rather than the fragment's text, so search matches the page that embeds a snippet only on the words the page itself carries.

Options