Snippet

Reuse parameterized MDX fragments across pages — build-time inlining via a remark plugin, zero runtime cost. Perfect for install blocks, common warnings, and shared product descriptions.

<Snippet> is Publier’s content-reuse primitive. You write an .mdx fragment once in a snippets directory, then reference it from any page with <Snippet file="..." /> and any number of {{placeholder}} props. The replacement happens at build time inside a remark plugin — compiled MDX has zero trace of <Snippet>.

Live demo

The block below is inlined from src/content/snippets/demo-install.mdx at build time, with {{package}} substituted per reference:

Install @publier/shell:

bun add @publier/shell

:::tip Need the dev variant? Add -D. :::

Install @publier/shell:

bun add @publier/shell

:::tip Need the dev variant? Add -D. :::

Two references, one source file. The {{package}} placeholder resolves differently for each reference.

Setup

Enable snippets once in astro.config.ts:

import { docsShell } from '@publier/shell/integration';

export default defineConfig({
  integrations: [
    docsShell({
      snippets: { directory: 'src/content/snippets' },
    }),
  ],
});

The directory is relative to the project root. Publier auto-registers the remark plugin when the snippets option is set.

Creating a snippet

Add any .mdx file to the snippets directory. Plain MDX — prose, code blocks, callouts, lists, nested components:

Install the package:

​```bash
pnpm add {{package}}
​```

:::tip
Need the dev variant? Add `-D`.
:::

{{package}} is a placeholder — it will be replaced at build time with whatever prop you pass when referencing the snippet.

Using a snippet

Embed the fragment anywhere in a regular page. Pass prop values by name:

## Install

<Snippet file="install.mdx" package="@publier/shell" />

## Install the UI package

<Snippet file="install.mdx" package="@publier/shell" />

Both references inline the same install.mdx fragment but substitute {{package}} with the respective value. The compiled output is equivalent to pasting the snippet body inline — no runtime component, no fetch, no hydration.

Multiple placeholders

Snippets accept any number of named placeholders:

This endpoint requires a **{{tier}}** plan or higher.
See the [pricing page]({{pricingUrl}}) for details.

<Snippet file="api-note.mdx" tier="Pro" pricingUrl="/pricing" />
<Snippet file="api-note.mdx" tier="Enterprise" pricingUrl="/contact-sales" />

Each reference substitutes its own values — one fragment, many configurations.

Nested snippets

Snippets can include other snippets. The remark plugin resolves them depth-first:

## Prerequisites

- Bun 1.1+

<Snippet file="install.mdx" package="{{package}}" />

Calling <Snippet file="prerequisites.mdx" package="@publier/shell" /> expands both fragments inline, with {{package}} threading through to the inner snippet.

Props

Path safety

file is resolved relative to the configured snippets directory. Path-traversal attempts (../, absolute paths, /etc/passwd) are rejected at build time with a warning, and the offending <Snippet> node is left in place as a visible fallback.

Directory layout

src/
  content/
    docs/
      get-started/
        installation.mdx   ← uses <Snippet file="install.mdx" />
    snippets/              ← configured via snippets.directory
      install.mdx          ← reusable fragment
      api-note.mdx
      prerequisites.mdx

Snippet files are excluded from the site’s route tree and search index — they only exist to be embedded. Move or rename them freely without breaking any URL.

Behaviour

• Remark plugin runs after MDX parsing, before compilation — final output is identical to pasting the snippet inline.
• Zero runtime cost — no <Snippet> component appears in the browser bundle.
• Unknown placeholders (prop name not passed) render as empty strings, not {{name}}.
• Missing files produce a build-time error naming the referrer page.

When to use Snippets

Related

• Build-time content transforms → Plugins guide.
• Site-wide variable substitution (no file) → vars: in publier.config.yaml.
• Themed pnpm add block → PackageInstall.