Deploying Your Documentation

This guide covers building your documentation for production and deploying to various platforms. Doom generates static HTML that can be served from any web server or hosting service.

Building for Production

Build static assets

Run the build command to generate production-ready files:

doom build

This creates optimized static files in the dist/ directory.

Preview the build

Test your production build locally:

doom serve

This starts a local server (default port 4173) serving your built documentation.

Deploy the dist folder

Upload the contents of the dist/ directory to your web server or hosting platform.

The doom serve command (also aliased as doom preview) lets you verify your production build before deployment.

Multi-Version Documentation

Doom supports building multiple versions of your documentation to maintain docs for different product releases.

Version Naming

Use the -v flag to specify a version:

# Build version-specific documentation
doom build -v 4.0   # Output: dist/4.0
doom build -v 4.1   # Output: dist/4.1
doom build -v master  # Output: dist/master

The documentation will be accessible at:

{base}/4.0
{base}/4.1
{base}/master

Unversioned Builds

For single-version documentation or when you don’t want version prefixes in URLs:

# Build without version in URL path
doom build -v unversioned
# Access at: {base}/ (no version prefix)

# Build with version shown in navbar but not in URL
doom build -v unversioned-4.0
# Access at: {base}/ but shows "v4.0" in the UI

Use unversioned for evergreen documentation or when you only maintain one version. Use unversioned-x.y when you want to indicate the version in the UI without URL versioning.

Multi-Version Directory Structure

A typical multi-version deployment looks like:

dist/
├── product-docs/
│   ├── 4.0/
│   │   ├── index.html
│   │   └── ...
│   ├── 4.1/
│   │   ├── index.html
│   │   └── ...
│   ├── index.html         # Version redirect page
│   ├── overrides.yaml     # Runtime config overrides
│   └── versions.yaml      # Version list

Version Redirect Page

Create an index.html at the root to redirect to the latest version:

dist/product-docs/index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Redirecting...</title>
    <meta http-equiv="refresh" content="0; url=/product-docs/4.1" />
  </head>
  <body>
    <p>Redirecting to <a href="/product-docs/4.1">/product-docs/4.1</a></p>
  </body>
</html>

Versions Configuration

List available versions in versions.yaml:

versions.yaml

- '4.1'  # Latest first
- '4.0'
- '3.9'

This powers the version selector in your documentation UI.

Build Automation Script

Here’s a shell script to build multiple versions:

build-versions.sh

#!/bin/bash

VERSIONS=("4.0" "4.1" "master")

for version in "${VERSIONS[@]}"; do
  echo "Building version $version..."
  doom build -v $version
done

echo "All versions built successfully!"

Make it executable and run:

chmod +x build-versions.sh
./build-versions.sh

Advanced Build Options

Custom Output Directory

Override the default output directory:

doom build -o custom-output

Output path becomes: dist/{outDir}/{version}

Base Path Override

Change the base URL path:

doom build -b /documentation

Your site will be accessible at https://example.com/documentation

Prefix Option

Add a prefix to the base path:

doom build -p /platform -b /docs

Result: https://example.com/platform/docs

Ignore Internal Routes

Exclude internal documentation pages:

doom build -i

This respects the internalRoutes configuration in your doom.config.yml.

Language Filtering

Build only specific languages:

# Include only English
doom build -I en

# Include only English and Russian
doom build -I en ru

# Exclude Chinese
doom build -E zh

Export Mode

Build for PDF export (excludes API routes):

doom build -e

This automatically excludes apis/** routes and optimizes for PDF generation.

Deployment Platforms

Vercel

Create vercel.json

Add configuration file:

vercel.json

{
  "buildCommand": "doom build",
  "outputDirectory": "dist",
  "installCommand": "npm install"
}

Connect repository

Import your repository in the Vercel dashboard.

Deploy

Vercel will automatically build and deploy on each push.

Netlify

Create netlify.toml

Add build configuration:

netlify.toml

[build]
  command = "doom build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Connect repository

Link your repository in the Netlify dashboard.

Deploy

Netlify will build and deploy automatically.

GitHub Pages

Create GitHub Actions workflow

Add .github/workflows/deploy.yml:

name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Build documentation
        run: npm run build
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Enable GitHub Pages

In repository settings:

Go to Pages
Source: Deploy from a branch
Branch: gh-pages

Configure base path

If deploying to a project page, set the base path:

doom.config.yml

base: /repository-name

Docker

Create a containerized deployment:

Dockerfile

FROM node:20-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

With Nginx configuration:

nginx.conf

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Build and run:

docker build -t my-docs .
docker run -p 8080:80 my-docs

Static Server

For any web server, simply copy the dist/ directory:

# Example: Copy to Apache
cp -r dist/* /var/www/html/docs/

# Example: Copy to Nginx
cp -r dist/* /usr/share/nginx/html/docs/

Dynamic Configuration

Use overrides.yaml to customize configuration per deployment environment:

overrides.yaml

title:
  en: Production Documentation
  zh: 生产环境文档
logoText:
  en: Prod Docs
  zh: 生产文档

Place this file alongside your built documentation. It’s loaded at runtime to override build-time configuration.

Use Cases

Multi-tenant deployments: Different branding per tenant
Environment-specific: Dev, staging, production configurations
Localization: Override text without rebuilding

Sites Configuration

For complex documentation ecosystems with multiple related sites, use sites.yaml:

sites.yaml

- name: main-docs
  base: /docs
  version: v4.1
  displayName:
    en: Main Documentation
    zh: 主文档
  repo: https://github.com/company/main-docs
  image: company/main-docs:latest

- name: api-reference
  base: /api
  version: v2.0
  displayName:
    en: API Reference
    zh: API 参考

This enables:

Cross-site references with <ExternalSite> component
Coordinated multi-version builds
Shared asset management

Sitemap Generation

Generate a sitemap for SEO:

doom build -S

Configure your site URL:

doom.config.yml

siteUrl: https://docs.example.com

This creates sitemap.xml in your output directory.

Performance Optimization

Build Performance

Use local cache: Avoid --force unless necessary
Limit language builds: Use -I to build only needed languages
Parallel builds: Build versions in parallel using CI/CD

Runtime Performance

CDN: Serve from a CDN for faster global access
Compression: Enable gzip/brotli compression on your server
Caching: Set long cache headers for static assets
Lazy loading: Doom automatically lazy-loads routes

Continuous Deployment

Example CI/CD pipeline for GitLab:

.gitlab-ci.yml

stages:
  - build
  - deploy

build:docs:
  stage: build
  image: node:20
  script:
    - npm install
    - doom build -v $CI_COMMIT_REF_NAME
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

deploy:production:
  stage: deploy
  only:
    - main
  script:
    - rsync -av dist/ /var/www/docs/
  environment:
    name: production
    url: https://docs.example.com

Troubleshooting

Assets not loading

Check your base path configuration:

base: /docs  # Must match your deployment path

Ensure all asset links use absolute paths: /images/logo.svg

404 errors on page refresh

Configure your server to redirect all requests to index.html:Nginx:

location / {
  try_files $uri $uri/ /index.html;
}

Apache (.htaccess):

RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

Version switcher not working

Ensure versions.yaml exists in your deployment:

- '4.1'
- '4.0'

Place it at the root level alongside version directories.

Build fails with out of memory

Increase Node.js memory limit:

NODE_OPTIONS="--max-old-space-size=4096" doom build

Or use the rebuild feature for large sites (automatically triggered when needed).

Next Steps

Versioning

Learn advanced version management strategies

PDF Export

Export documentation to PDF format

Build Command

Detailed build command reference

Configuration

Explore all configuration options

Get Started

Core Concepts

Features

Guides

​Deploying Your Documentation

​Building for Production

​Multi-Version Documentation

​Version Naming

​Unversioned Builds

​Multi-Version Directory Structure

​Version Redirect Page

​Versions Configuration

​Build Automation Script

​Advanced Build Options

​Custom Output Directory

​Base Path Override

​Prefix Option

​Ignore Internal Routes

​Language Filtering

​Export Mode

​Deployment Platforms

​Vercel

​Netlify

​GitHub Pages

​Docker

​Static Server

​Dynamic Configuration

​Use Cases

​Sites Configuration

​Sitemap Generation

​Performance Optimization

​Build Performance

​Runtime Performance

​Continuous Deployment

​Troubleshooting

​Next Steps

Versioning

PDF Export

Build Command

Configuration

Build docs developers (and LLMs) love

Deploying Your Documentation

Building for Production

Multi-Version Documentation

Version Naming

Unversioned Builds

Multi-Version Directory Structure

Version Redirect Page

Versions Configuration

Build Automation Script

Advanced Build Options

Custom Output Directory

Base Path Override

Prefix Option

Ignore Internal Routes

Language Filtering

Export Mode

Deployment Platforms

Vercel

Netlify

GitHub Pages

Docker

Static Server

Dynamic Configuration

Use Cases

Sites Configuration

Sitemap Generation

Performance Optimization

Build Performance

Runtime Performance

Continuous Deployment

Troubleshooting

Next Steps