> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reusable Snippets

Create reusable content snippets that can be shared across multiple documentation pages.

## 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.

```
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 _snippets/prerequisites.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 _snippets/install-cli.mdx
Install the HolyDocs CLI using your preferred package manager:

<CodeGroup>
```bash npm
npm install -g @holydocs/cli
```
```bash pnpm
pnpm add -g @holydocs/cli
```
```bash yarn
yarn global add @holydocs/cli
```
</CodeGroup>

Verify the installation:

```bash
holydocs --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 quickstart.mdx
---
title: Quickstart
description: Get started with HolyDocs in under 5 minutes.
---

## Prerequisites

import Prerequisites from './_snippets/prerequisites.mdx';

<Prerequisites />

## Install the CLI

import InstallCli from './_snippets/install-cli.mdx';

<InstallCli />

## Create Your Project

Run the init command to scaffold a new docs project:

```bash
mkdir 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:

```
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 _snippets/notices/beta-warning.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 _snippets/auth/bearer-token.mdx
All API requests must include a bearer token in the `Authorization` header:

```bash
curl -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 _snippets/setup/install-sdk.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 _snippets/setup/prerequisites.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 _snippets/notices/enterprise-only.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 _snippets/endpoint-base.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 _snippets/deploy-steps.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

**Use the _snippets/ directory convention**

Keep all snippets in a `_snippets/` directory at the docs root. The underscore prefix ensures HolyDocs excludes these files from navigation, search indexing, and sitemap generation. Avoid scattering snippet files across content directories.
  **Name snippets descriptively**

Use clear, descriptive filenames: `auth-bearer-token.mdx` is better than `snippet-1.mdx`. When you have dozens of snippets, good names make them discoverable without opening every file.
  **Keep snippets focused**

Each snippet should cover one concept or block of content. A snippet that covers authentication setup, rate limiting, and error handling is doing too much — split it into three. Focused snippets are easier to reuse and maintain.
  **Document snippet purpose with comments**

Add an HTML comment at the top of complex snippets explaining what they contain and where they are used. This helps contributors understand the snippet's purpose without tracing all its import locations.
  **Avoid deeply nested snippet imports**

A snippet should not import other snippets. One level of nesting is manageable; deeper chains become hard to trace and debug. If you need to compose complex reusable blocks, build them as a single snippet.