Reusable Snippets

Snippet types

How snippets work

Snippets are repository files stored in the top-level snippets/ directory. Documentation.AI supports Markdown snippets in .md and .mdx files, plus React component snippets in .jsx files. The editor inserts a reference to the source file rather than copying its content into the page.

Key behaviors:

• Pages store a file path reference, not a copy of the content.
• Each snippet renders as an atomic, non-editable block with a live preview.
• Editing the source file updates every page that imports the snippet after the next render or deployment.
• Snippets support nesting up to 5 levels deep.

Create a snippet

From the web editor

Use the Snippet slash command to create a new snippet.

From the code editor

Create a file directly under the top-level snippets/ directory. Use .md or .mdx for Markdown and MDX content, or .jsx for a React component.

For example:

snippets/
├── api-authentication.mdx
└── status-card.jsx

The filename determines the component name the editor displays. The file path is the source of truth for every page that imports the snippet.

Insert a snippet into a page

In the web editor

Insert an existing snippet with the Snippet slash command.

The pencil button on the snippet block opens the source file for editing.

In the code editor

Import a snippet with a default import and render the generated component name as a self-closing element.

import ApiAuthentication from "/snippets/api-authentication.mdx"

<ApiAuthentication />

import StatusCard from "/snippets/status-card.jsx"

<StatusCard />

The import path must point to a file under snippets/. Documentation.AI recognizes default imports as visible snippet references. Named imports remain ordinary ESM and are not converted into snippet blocks by the editor.

MDX snippets

MDX snippets contain Markdown or MDX content, including text, headings, code blocks, and Documentation.AI components.

The editor removes frontmatter from the live preview, but the source file can still use frontmatter. A newly created Markdown snippet starts with:

---
title: api-authentication
---

Add the reusable content below the frontmatter:

---
title: api-authentication
---

Authenticate requests with an API key in the `Authorization` header.

<Callout kind="info">

Keep API keys out of client-side code and public repositories.

</Callout>

When you insert the snippet, the page renders the body content and supported MDX components. The snippet's frontmatter does not appear inside the importing page.

React component snippets

React component snippets are stored in .jsx files. Documentation.AI compiles them in the browser and renders the component in the snippet preview. React hooks, component state, and browser APIs are supported.

A React component snippet must use named exports only. The component name should match the filename-derived component name. For example, status-card.jsx should contain:

export const description = "Displays the current publishing status"

export const StatusCard = () => {
  return (
    <div className="my-6 rounded-lg border p-4">
      <strong>Publishing status</strong>
      <p>Your documentation is ready to publish.</p>
    </div>
  )
}

The optional description export provides searchable metadata. It does not affect the rendered component.

The editor reports syntax, missing-component, and runtime errors in the snippet preview. Keep the component self-contained because the snippet node does not currently provide a props editor or pass attributes from the importing page.

Anti-patterns

Avoid these common mistakes when writing React component snippets.

Manage snippets

Edit the source file to update a reusable snippet. Pages that import the snippet render the updated source, so one change keeps every occurrence aligned.

Removing a snippet from a page deletes only that occurrence. The source file remains in snippets/, and other pages that use the same snippet are unchanged.

If a source file is renamed, moved, or deleted, its existing reference remains on the page and displays Unable to load snippet. The edit control is disabled until the source file is available again, but you can remove the broken reference from the page.

Deployment and search

Documentation.AI validates snippets during deployment and deploys each snippet as an independent file. MDX snippet content is expanded into importing pages during search indexing, so reusable prose and headings can be found through documentation search.

Snippet imports inside code blocks are treated as example code. Documentation.AI does not expand those imports during search indexing, so you can safely show import syntax in a code sample.

What's next