Static hosts

A static build is a folder of plain files. Any host that serves files works. This page lists the settings each common host needs.

Build the siteCopy Anchor Link

cd docs
npx orbitdocs build

The site is in out/. Every page is a folder with an index.html (/quickstart/ is out/quickstart/index.html), and out/404.html is the not-found page.

orbitdocs deploy --target static runs the same build and prints where to upload. It does not upload anything.

What every host needsCopy Anchor Link

Redirects from the redirects config are written two ways:

• A small HTML page per redirect without a *. It forwards the reader on any host.
• An out/_redirects file with every rule, wildcards included. Netlify and Cloudflare Pages read it. Other hosts ignore it.

NetlifyCopy Anchor Link

Netlify reads out/_redirects, so wildcard redirects work.

Cloudflare PagesCopy Anchor Link

Build locally and upload with Wrangler:

npx orbitdocs build
npx wrangler pages deploy out --project-name acme-docs

To build on Cloudflare instead, set the root directory to docs, the build command to npm ci --prefix .. && npx orbitdocs build, the output directory to out, and NODE_VERSION to 22. Cloudflare Pages reads out/_redirects.

GitHub PagesCopy Anchor Link

A project site lives under the repository name, for example https://acme.github.io/payments/. Set the base path to match:

output: { mode: 'static', basePath: '/payments' },

Deploy with GitHub Actions. This workflow builds the Nest app and the docs, then publishes docs/out:

name: Docs
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm ci
        working-directory: docs
      - run: npx orbitdocs build
        working-directory: docs
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/out
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

In the repository settings, set Pages → Source to GitHub Actions.

GitHub Pages ignores _redirects. Only redirects without * work there.

S3 + CloudFrontCopy Anchor Link

npx orbitdocs build
aws s3 sync out/ s3://acme-docs --delete
aws cloudfront create-invalidation --distribution-id E123EXAMPLE --paths "/*"

CloudFront only maps / to index.html on its own. For /quickstart/ to load quickstart/index.html, do one of these:

• Use the bucket's static website endpoint as the CloudFront origin. It resolves folder index files.
• Keep the REST endpoint and add a CloudFront Function on viewer requests that appends index.html to paths ending in /.

Set the distribution's custom error response for 404 to /404.html.

nginxCopy Anchor Link

Copy out/ to the server and point a location at it:

server {
  listen 80;
  server_name docs.acme.com;
  root /var/www/docs;

  location / {
    try_files $uri $uri/ $uri.html =404;
  }

  error_page 404 /404.html;
}

With basePath: '/docs', serve the folder under that path:

location /docs {
  alias /var/www/docs/;
  try_files $uri $uri/ $uri.html =404;
}
error_page 404 /docs/404.html;

This is the same config orbitdocs deploy --target docker writes. See Docker for a ready image.

Private docs and Ask AICopy Anchor Link

A static host cannot check who is reading or call an LLM. Gated pages are served to everyone, and the Ask AI button stays hidden. When you need either feature, deploy with server mode, inside your Nest app or on the platform.

Next stepsCopy Anchor Link