Reusable Snippets

Overview

Snippets are reusable blocks of MDX content that you define once and include in multiple pages. They reduce duplication, keep shared content consistent, and make updates easier — change the snippet in one place, and every page that uses it is updated on the next build.

Common use cases include shared installation instructions, authentication setup blocks, deprecation notices, and prerequisite checklists.

Creating Snippets

Snippets are regular MDX files stored in a _snippets/ directory at your docs root. Files prefixed with an underscore (_) or placed inside underscore-prefixed directories are excluded from navigation and not treated as standalone pages.

text
docs/  docs.json  introduction.mdx  quickstart.mdx  _snippets/    prerequisites.mdx    auth-setup.mdx    install-cli.mdx    rate-limit-warning.mdx

A snippet file contains standard MDX content — text, components, code blocks — without frontmatter:

mdx
<Callout type="info">  Before you begin, make sure you have:  - Node.js 18 or later installed  - A HolyDocs account ([sign up free](https://app.holydocs.com))  - Git installed and configured</Callout>

mdx
Install the HolyDocs CLI using your preferred package manager:<CodeGroup>```bash npmnpm install -g @holydocs/cli``````bash pnpmpnpm add -g @holydocs/cli``````bash yarnyarn global add @holydocs/cli```</CodeGroup>Verify the installation:```bashholydocs --version```

Snippet files do not require frontmatter. They are not rendered as standalone pages, so title and description fields are unnecessary. If frontmatter is present, it is ignored during import.

Using Snippets

Import and render a snippet in any MDX page using the standard MDX import syntax:

mdx
---title: Quickstartdescription: Get started with HolyDocs in under 5 minutes.---## Prerequisitesimport Prerequisites from './_snippets/prerequisites.mdx';<Prerequisites />## Install the CLIimport InstallCli from './_snippets/install-cli.mdx';<InstallCli />## Create Your ProjectRun the init command to scaffold a new docs project:```bashmkdir my-docs && cd my-docs && holydocs init```

The imported snippet content is inlined at the position of the <ComponentName /> tag during the build.

Import Rules

• Import paths are relative to the file that contains the import statement
• The import name (e.g., Prerequisites) can be any valid JavaScript identifier
• Each snippet must be imported before it is used on the page
• A snippet can be imported and used multiple times on the same page

Organizing Snippets

For larger documentation projects, organize snippets into subdirectories by category:

text
docs/  _snippets/    auth/      bearer-token.mdx      api-key.mdx      oauth-setup.mdx    notices/      beta-warning.mdx      enterprise-only.mdx      rate-limit.mdx    setup/      prerequisites.mdx      install-cli.mdx      environment-variables.mdx

Import from nested directories using the relative path:

mdx
import BearerToken from './_snippets/auth/bearer-token.mdx';import BetaWarning from './_snippets/notices/beta-warning.mdx';<BetaWarning />## Authentication<BearerToken />

Common Snippet Patterns

Shared Warning or Notice

mdx
<Callout type="warning" title="Beta Feature">  This feature is currently in beta and may change without notice. Do not use it in production workflows without testing thoroughly.</Callout>

Authentication Instructions

mdx
All API requests must include a bearer token in the `Authorization` header:```bashcurl -H "Authorization: Bearer YOUR_API_KEY" \  https://api.holydocs.com/v1/projects```You can generate an API key in the [Dashboard Settings](https://app.holydocs.com/settings/api).

Installation Block

mdx
<Tabs>  <Tab title="npm">    ```bash    npm install @holydocs/sdk    ```  </Tab>  <Tab title="pnpm">    ```bash    pnpm add @holydocs/sdk    ```  </Tab>  <Tab title="yarn">    ```bash    yarn add @holydocs/sdk    ```  </Tab></Tabs>

Prerequisite Checklist

mdx
<Expandable title="Prerequisites">  Before starting this guide, ensure you have:  - **Node.js 20+** — [Download](https://nodejs.org/)  - **HolyDocs CLI** — Run `npm install -g @holydocs/cli`  - **Git** configured with access to your repository  - A **HolyDocs project** created in the [Dashboard](https://app.holydocs.com)</Expandable>

Enterprise Feature Gate

mdx
<Callout type="info" title="Enterprise Plan">  This feature is available on the Enterprise plan. [Contact sales](https://holydocs.com/enterprise) to learn more, or see [Plans & Pricing](/plans-pricing) for a full comparison.</Callout>

Variables in Snippets

Snippets can accept props to customize their content at the point of use. Define your snippet as a component that receives props:

mdx
export const EndpointBase = ({ method, path }) => (  <div>    The base URL for this endpoint is:    ```    {method} https://api.holydocs.com{path}    ```  </div>);

Use it with props in your page:

mdx
import { EndpointBase } from './_snippets/endpoint-base.mdx';<EndpointBase method="GET" path="/v1/projects" />

When to Use Variables

Variables are useful when the snippet structure is identical but specific values change across pages — API base URLs, version numbers, package names, and configuration keys are good candidates.

For content that differs substantially between uses, consider creating separate snippets instead of overloading a single one with many conditional props.

Snippets with Components

Snippets can contain any HolyDocs component. The built-in components (Callout, Card, CodeGroup, Steps, Tabs, Accordion, etc.) are available without imports:

mdx
<Steps>  <Step title="Build your docs">    ```bash    holydocs build    ```  </Step>  <Step title="Preview locally">    ```bash    holydocs dev    ```    Open [http://localhost:3333](http://localhost:3333) to preview.  </Step>  <Step title="Deploy to production">    ```bash    holydocs deploy    ```  </Step></Steps>

Best Practices