Skip to main content

Documentation Deployment

How to deploy the Sprout documentation site.

Overview​

The documentation is built with Docusaurus and can be deployed as a static site to Cloudflare Pages.

Prerequisites​

  • Cloudflare account
  • Git repository access
  • Cloudflare Pages access

Local Build​

Before deploying, test the build locally:

cd /Users/stef/apps/sprout/sprout_docs

# Install dependencies
bun install

# Build the site
bun run build

# Preview the build
bun run serve

The build output will be in the build/ directory.

Cloudflare Pages Deployment​

Quick Deploy​

The easiest way to deploy:

# Build and deploy
bun run deploy

First time setup:

  1. Authenticate with Cloudflare: 
    bunx wrangler login
  2. Create the Pages project (if it doesn't exist): 
    bunx wrangler pages project create sprout-docs
  3. Deploy: 
    bun run deploy

Option 1: Automatic Deployment via Git​

  1. Connect Repository:

    • Go to Cloudflare Dashboard → Pages
    • Click "Create a project"
    • Connect your Git repository
    • Select the sprout_docs directory

  2. Build Settings:

    • Framework preset: Docusaurus
    • Build command: bun install && bun run build
    • Build output directory: build
    • Root directory: /sprout_docs (if in monorepo)

  3. Environment Variables (if needed):

    • Add any required environment variables
    • Most Docusaurus configs don't need env vars

  4. Deploy:

    • Cloudflare will automatically deploy on push to main/master
    • Or trigger manual deployment from dashboard

Option 2: Manual Deployment via Wrangler​

The project is configured with wrangler.toml.

Deploy command:

bun run deploy

This runs:

  1. bun run build - Builds the Docusaurus site
  2. bunx wrangler pages deploy build --project-name=sprout-docs - Deploys to Cloudflare Pages

Manual steps (if needed):

# Build
bun run build

# Deploy
bunx wrangler pages deploy build --project-name=sprout-docs

Authentication: First time, you'll need to login:

bunx wrangler login

Option 3: GitHub Actions​

Create .github/workflows/deploy-docs.yml:

name: Deploy Docs

on:
  push:
    branches:
      - main
    paths:
      - 'sprout_docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest
      
      - name: Install dependencies
        working-directory: sprout_docs
        run: bun install
      
      - name: Build
        working-directory: sprout_docs
        run: bun run build
      
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: sprout-docs
          directory: sprout_docs/build

Custom Domain​

  1. Add Custom Domain in Cloudflare:

    • Go to Pages project settings
    • Add custom domain (e.g., docs.sproutproperties.co)
    • Follow DNS setup instructions

  2. Update Docusaurus Config: Update docusaurus.config.ts:

    url: 'https://docs.sproutproperties.co',
    baseUrl: '/',

Build Configuration​

Build Settings​

The build process:

  1. Installs dependencies with bun install
  2. Builds TypeScript and React with bun run build
  3. Outputs static files to build/ directory

Build Optimization​

Docusaurus automatically:

  • Optimizes images
  • Minifies JavaScript and CSS
  • Generates sitemap
  • Creates search index

Continuous Deployment​

Automatic Deployments​

  • On push to main: Automatic deployment
  • On pull requests: Preview deployments (optional)

Preview Deployments​

Cloudflare Pages creates preview deployments for PRs:

  • Unique URL per PR
  • Allows review before merge
  • Automatically cleaned up after PR close

Troubleshooting​

Build Fails​

  1. Check build logs in Cloudflare dashboard
  2. Test locally first: 
    bun run build
  3. Verify dependencies are installed correctly

Missing Files​

  1. Check build output directory
  2. Verify static files are in static/ directory
  3. Check file paths in documentation

Search Not Working​

  1. Verify search plugin is configured
  2. Check build includes search index
  3. Wait for indexing (may take a few minutes)

Manual Updates​

To update documentation:

  1. Make changes to markdown files
  2. Commit and push to repository
  3. Cloudflare automatically rebuilds and deploys
  4. Changes go live in 1-2 minutes

Backup​

Documentation is version-controlled in Git, so:

  • All changes are tracked
  • Can rollback via Git
  • No separate backup needed

Performance​

Cloudflare Pages provides:

  • Global CDN distribution
  • Automatic HTTPS
  • Fast page loads
  • Free SSL certificates

Next Steps​