Deploying

Verne writes a self-contained public/ directory. Drop it on any static host and you’re done. There is no server-side runtime to worry about.

The one config detail#

Set baseURL: in verne.yaml to the canonical, public URL of the site, including the scheme and trailing slash:

baseURL: "https://docs.example.com/"

baseURL is concatenated into the sitemap, RSS feeds, JSON-LD payloads, canonical <link> tags, and Open Graph URLs. A wrong value here means search engines index the wrong host. Verne validates the format at build time and refuses non-http(s):// schemes.

GitHub Pages#

# .github/workflows/deploy.yml
name: deploy
on: { push: { branches: [main] } }
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          # Build Verne from source until pre-built releases ship
          curl -L https://github.com/davlgd/Verne/archive/main.tar.gz | tar xz
          cd Verne-main && mise run prod && sudo install verne /usr/local/bin/
      - run: verne build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

If you serve under a subpath (https://username.github.io/repo/), set baseURL: "https://username.github.io/repo/" accordingly.

Cloudflare Pages, Netlify, Vercel#

Set the build command to verne build and the publish directory to public. None of these hosts require a runtime — they serve the static output directly.

A self-hosted Caddy / nginx example#

docs.example.com {
    root * /var/www/docs/public
    file_server
    encode zstd gzip
    header Cache-Control "public, max-age=300, must-revalidate"
    header /css/* Cache-Control "public, max-age=31536000, immutable"
    header /js/*  Cache-Control "public, max-age=31536000, immutable"
}

Verne fingerprints the CSS / JS bundles (bundle.46a0a036.css, app.24717767.js) so they’re safe to cache aggressively — every change gets a fresh hash.

Sanity checks#

After deploying, hit:

• /sitemap.xml — should list every page
• /robots.txt — should reference the sitemap
• A nested page like /guides/quick-start/ — should load with no 404s
• The on-this-page TOC links — should jump to anchors, not 404 fragments

If anything’s off, run verne build locally and diff your public/ against what the host serves.