documentation-docusaurus/references/deployment.md

Deployment

Getting your docs live. Pick the platform that fits your workflow.

---

Quick Decision

Platform	Best For	Effort
Vercel	Teams already using Vercel	Lowest
Netlify	Need redirects, forms, functions	Low
GitHub Pages	Open source, simple hosting	Low
Cloudflare Pages	Global performance, free tier	Low

My recommendation: Vercel or Netlify for most projects. GitHub Pages if you want everything in one repo.

---

Vercel

Setup

1. Push to GitHub
2. Import at vercel.com
3. Done—it auto-detects Docusaurus

Config (vercel.json, usually not needed)

{
  "buildCommand": "npm run build",
  "outputDirectory": "build"
}

Vercel handles this automatically. Only add if you need overrides.

---

Netlify

Setup

1. Push to GitHub
2. Connect at app.netlify.com
3. Build command: npm run build
4. Publish directory: build

Config (netlify.toml)

[build]
  command = "npm run build"
  publish = "build"

[[redirects]]
  from = "/old-path"
  to = "/new-path"
  status = 301

Opinion: Netlify's redirect handling is cleaner than most.

---

GitHub Pages

Config

// docusaurus.config.ts
const config = {
  url: 'https://username.github.io',
  baseUrl: '/repo-name/',  // or '/' for username.github.io
  organizationName: 'username',
  projectName: 'repo-name',
  trailingSlash: false,
};

GitHub Actions (recommended)

.github/workflows/deploy.yml:

name: Deploy

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: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Enable Pages in repo settings → Pages → Source: GitHub Actions.

---

Cloudflare Pages

Setup

1. Connect repo at pages.cloudflare.com
2. Framework: None (not auto-detected well)
3. Build command: npm run build
4. Output directory: build

Why Cloudflare

• Fastest global CDN
• Generous free tier
• Web analytics included

---

Pre-Deployment Checklist

Before pushing:

# 1. Build locally first
npm run build

# 2. Test the build
npm run serve

# 3. Check for broken links (build will fail if onBrokenLinks: 'throw')
# 4. Verify all images load
# 5. Test search works (if Algolia configured)

---

Custom Domain

All platforms support custom domains. General steps:

1. Add domain in platform settings
2. Update DNS:
   • A record to platform IP, or
   • CNAME to platform URL
3. Wait for SSL certificate (automatic, usually minutes)
4. Update url in docusaurus.config.ts

DNS propagation: Can take up to 48 hours. Usually much faster.

---

Environment-Specific Builds

For staging vs production:

const isProd = process.env.NODE_ENV === 'production';

const config = {
  url: isProd
    ? 'https://docs.example.com'
    : 'https://staging-docs.example.com',
};

Or use platform environment variables.

---

Common Issues

Build Fails Locally But Worked Before

rm -rf node_modules .docusaurus
npm ci
npm run build

Build Works Locally, Fails in CI

• Check Node.js version matches
• Check for case-sensitive filename issues (Linux is case-sensitive, macOS isn't)
• Check for absolute paths that only exist on your machine

"Page Not Found" After Deploy

• Check baseUrl matches your hosting path
• Check trailingSlash is consistent
• Clear CDN cache if platform supports it