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

# holydocs build

Generate a static HTML build of your documentation for self-hosting or offline use.

## Usage

```bash
holydocs build [options]
```

Generates a complete static HTML site from your documentation project. The build uses the same rendering pipeline as `holydocs dev` and production deployments, processing every MDX page through the full unified pipeline (remark, rehype, theme CSS, layout template) and writing the result to disk.

## Options

| Option | Description | Default |
|---|---|---|
| `--dir <path>` | Root directory of the docs project | Auto-detected |
| `--out <dir>` | Output directory name (relative to project root) | `dist` |

## Examples

### Basic Build

```bash
holydocs build
```

Output:

```
  HolyDocs Build

  Project: My API Docs
  Theme:   holy
  Output:  /path/to/project/dist
  Pages:   42

  ✓ introduction
  ✓ quickstart
  ✓ guides/getting-started
  ✓ api-reference/list-users
  ...

  Built 42 pages and 15 assets in 3.2s → /path/to/project/dist
```

### Custom Output Directory

```bash
holydocs build --out build
```

Writes the static site to `./build` instead of the default `./dist` directory.

### Build from a Specific Directory

```bash
holydocs build --dir ./docs
```

Useful when your documentation lives in a subdirectory of a larger repository.

### Build with OpenAPI Spec

If your `docs.json` references an OpenAPI spec, the build automatically loads it, enriches endpoints with code samples, and renders full API reference pages alongside your regular documentation.

## Output Structure

The build command produces a self-contained static site:

```
dist/
  introduction/
    index.html
  quickstart/
    index.html
  guides/
    getting-started/
      index.html
  api-reference/
    list-users/
      index.html
  _assets/
    images/
      hero.png
    logo.svg
```

Each page is written as `<slug>/index.html` for clean URLs. Static assets (images, fonts, videos, CSS, JS, PDFs) are copied into the `_assets/` directory.

### Supported Asset Types

| Category | Extensions |
|---|---|
| Images | `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.ico` |
| Fonts | `.woff`, `.woff2`, `.ttf`, `.otf`, `.eot` |
| Media | `.mp4`, `.webm`, `.ogg`, `.mp3` |
| Other | `.pdf`, `.css`, `.js` |

## Build Pipeline

The build processes each page through the same pipeline used in production:

**Load Configuration**

Reads `docs.json` (or `mint.json` for Mintlify compatibility), resolves variables, loads snippets from `_snippets/`, and discovers custom components in `_components/`.
  **Generate Theme CSS**

Produces theme-specific CSS based on your configuration (colors, fonts, theme preset).
  **Process Pages**

Each MDX file is run through the unified pipeline: remark-parse, remark-mdx, remark-gfm, remark-toc, rehype-slug, rehype-code-blocks, and more. Frontmatter is extracted, variables are interpolated, and snippets are expanded.
  **Render OpenAPI Pages**

Pages with `openapi` frontmatter are matched to spec endpoints. The API reference layout, parameter tables, and playground HTML are generated.
  **Write HTML**

Each processed page is wrapped in the full HTML template (sidebar, navigation, table of contents, theme CSS, component CSS) and written to disk.
  **Copy Assets**

Static files are discovered recursively and copied to `_assets/`, skipping `node_modules`, `.`-prefixed directories, `_snippets`, and `_components`.

## Configuration Requirement

The build command requires a valid `docs.json` or `mint.json` in the project root. If neither is found, the command exits with an error:

```
Error: No docs.json or mint.json found. Run `holydocs init` first.
```

Run `holydocs check` before building to catch configuration or content errors early. The build command will attempt to render every page and report failures, but `check` provides more detailed diagnostics.

## Error Handling

If individual pages fail to render, the build continues and reports failures at the end:

```
  ✓ introduction
  ✗ api-reference/broken-page: Invalid MDX syntax at line 12
  ✓ quickstart

  Built 41 pages (1 failed), 15 assets in 3.5s → dist
```

The process exits with code `1` when any page fails, making it suitable for CI pipelines where you want the build to fail on errors.

## Self-Hosting

The output of `holydocs build` is a fully static site that can be served by any HTTP server:

```bash
# Quick local preview
npx serve dist

# Deploy to any static host
netlify deploy --dir dist
```

The static build does not include server-side features like AI search, the API playground with live requests, or analytics. For the full feature set, deploy to HolyDocs with `holydocs deploy`.

## Related

- [holydocs dev](/cli/dev) -- Local development server with hot reload
- [holydocs deploy](/cli/deploy) -- Deploy to the HolyDocs edge network
- [holydocs check](/cli/check) -- Validate configuration before building