holydocs build
Generate a static HTML build of your documentation for self-hosting or offline use.
Usage
bashholydocs 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
bashholydocs build
Output:
textHolyDocs 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
bashholydocs build --out build
Writes the static site to ./build instead of the default ./dist directory.
Build from a Specific Directory
bashholydocs 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:
textdist/ 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:
textError: 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:
text✓ 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 previewnpx serve dist# Deploy to any static hostnetlify 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 -- Local development server with hot reload
- holydocs deploy -- Deploy to the HolyDocs edge network
- holydocs check -- Validate configuration before building