Lantern

Appearance

Documentation Site Deployment Guide ​

Complete guide for deploying the VitePress documentation site to docs.ourlantern.app and docs.dev.ourlantern.app.

Overview ​

The documentation site is separate from the main Lantern app and has its own deployment pipeline:

ComponentProductionDevelopment
Main Appourlantern.appdev.ourlantern.app
Docs Sitedocs.ourlantern.appdocs.dev.ourlantern.app

Key Benefits:

  • Independent deployment cycles
  • Faster docs updates without rebuilding the app
  • Cleaner separation of concerns
  • Can update docs without affecting app stability

Deployment Flow ​

Push to GitHub (main or dev branch)
    ↓
GitHub Actions (deploy-docs.yml)
    ↓
Build VitePress site (npm run docs:build)
    ↓
Deploy to Cloudflare Pages
    ↓
Available at docs.ourlantern.app (main) or docs.dev.ourlantern.app (dev)

Automatic Deployments ​

  • main branch → docs.ourlantern.app (production)
  • dev branch → docs.dev.ourlantern.app (development)
  • feature branches → Preview URLs (e.g., feature-xyz.lantern-docs-dev.pages.dev)

Quick Start ​

Local Development ​

bash
# Start the docs dev server
npm run docs:dev

# Build docs for production
npm run docs:build

# Preview the production build locally
npm run docs:preview

The dev server runs on http://localhost:5173 by default.

Initial Setup in Cloudflare ​

Step 1: Create Production Docs Project ​

  1. Go to Cloudflare Dashboard → Pages
  2. Click "Create a project" → "Connect to Git"
  3. Select cattreedev/lantern_app repository
  4. Configure:
    • Project name: lantern-docs
    • Production branch: main
    • Build command: npm run docs:build
    • Build output directory: docs/.vitepress/dist
    • Root directory: (leave empty)
  5. Click "Save and Deploy"

Step 2: Create Development Docs Project ​

  1. Click "Create a project" again
  2. Select same repo cattreedev/lantern_app
  3. Configure:
    • Project name: lantern-docs-dev
    • Production branch: dev (not main!)
    • Build command: npm run docs:build
    • Build output directory: docs/.vitepress/dist
    • Root directory: (leave empty)
  4. Click "Save and Deploy"

Step 3: Add Custom Domains ​

Production Docs ​

  1. In lantern-docs project, go to Settings → Domains & accounts
  2. Click Add domain
  3. Enter docs.ourlantern.app
  4. Cloudflare will auto-create the required DNS records

Development Docs ​

  1. In lantern-docs-dev project, go to Settings → Domains & accounts
  2. Click Add domain
  3. Enter docs.dev.ourlantern.app
  4. Cloudflare will auto-create the required DNS records

Step 4: Verify DNS Configuration ​

In Cloudflare dashboard, DNS tab should show:

CNAME  docs           → lantern-docs.pages.dev        (Proxied)
CNAME  docs-dev       → lantern-docs-dev.pages.dev    (Proxied)

Note: These are in addition to your existing app DNS records:

CNAME  @              → lantern-app.pages.dev         (Proxied)
CNAME  dev            → lantern-app-dev.pages.dev     (Proxied)

GitHub Actions Setup ​

Required Secrets ​

Add these secrets in your GitHub repository:

  1. Go to Settings → Secrets and variables → Actions
  2. Add the following repository secrets:
Secret NameHow to Get It
CLOUDFLARE_API_TOKENCloudflare Dashboard → My Profile → API Tokens → Create Token → "Edit Cloudflare Workers" template
CLOUDFLARE_ACCOUNT_IDCloudflare Dashboard → Workers & Pages → Account ID (right sidebar)

Note: The GITHUB_TOKEN is automatically provided by GitHub Actions.

Workflow File ​

The workflow is configured in .github/workflows/deploy-docs.yml. It:

  • Triggers on pushes to main or dev branches (when docs files change)
  • Triggers on pull requests (for preview deployments)
  • Can be manually triggered via workflow_dispatch
  • Builds the VitePress site
  • Deploys to the appropriate Cloudflare Pages project

Deployment Workflow ​

Updating Documentation ​

1. Make Changes ​

bash
# Create a feature branch
git checkout -b feature/update-docs dev

# Edit documentation files in docs/
# ... make changes ...

# Test locally
npm run docs:dev
# Visit http://localhost:5173 to preview

2. Build and Test ​

bash
# Build docs to verify no errors
npm run docs:build

# Preview the built site
npm run docs:preview

3. Push to GitHub ​

bash
git add docs/
git commit -m "docs: Update XYZ documentation"
git push origin feature/update-docs

Result: GitHub Actions creates a preview deployment

  • Preview URL: https://feature-update-docs.lantern-docs-dev.pages.dev
  • Check the Actions tab for deployment status
  • Preview link appears in the PR

4. Merge to Dev ​

bash
git checkout dev
git merge feature/update-docs
git push origin dev

Result: Automatically deploys to https://docs.dev.ourlantern.app

5. Deploy to Production ​

bash
git checkout main
git merge dev
git push origin main

Result: Automatically deploys to https://docs.ourlantern.app

Monitoring Deployments ​

Via GitHub Actions ​

  1. Go to your repository on GitHub
  2. Click Actions tab
  3. Select Deploy Documentation workflow
  4. View recent runs and their status
  5. Click on a run to see detailed logs

Via Cloudflare Dashboard ​

  1. Go to Pages in Cloudflare Dashboard
  2. Select lantern-docs or lantern-docs-dev
  3. View deployment history
  4. See build logs and deployment status

Troubleshooting ​

Build Fails with "vitepress: not found" ​

Cause: Dependencies not installed

Fix: Ensure npm ci runs before build (this is automatic in GitHub Actions)

Deployment Succeeds but Site Shows 404 ​

Cause: Wrong build output directory

Fix: Verify in Cloudflare Pages settings:

  • Build output directory: docs/.vitepress/dist
  • NOT dist or .vitepress/dist

Changes Not Appearing After Deployment ​

Cause: Browser cache or Cloudflare cache

Fix:

  1. Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)
  2. Or purge Cloudflare cache: Pages project → Deployments → "Retry deployment"

GitHub Actions Fails with Permission Error ​

Cause: Missing or invalid Cloudflare API token

Fix:

  1. Verify CLOUDFLARE_API_TOKEN secret is set correctly
  2. Ensure token has "Edit Cloudflare Workers" permissions
  3. Check token hasn't expired

Preview Deployments Not Working ​

Cause: GitHub Actions not triggered on PRs

Fix: Ensure the workflow file has:

yaml
on:
  pull_request:
    paths:
      - 'docs/**'

Features Enabled ​

Dark Theme ​

  • Dark mode is enabled by default (appearance: 'dark' in config)
  • Users can toggle between light/dark with the theme switcher in the nav
  • Local search is enabled (search: { provider: 'local' })
  • Indexes all markdown content automatically
  • No external dependencies or API keys needed
  • Organized by category (Getting Started, Engineering, Features, etc.)
  • Collapsible sections for better organization
  • Auto-generated from file structure

Markdown Enhancements ​

  • Line numbers enabled for code blocks
  • Syntax highlighting
  • Frontmatter support
  • Custom containers (tip, warning, danger, etc.)

Updating Documentation ​

Adding New Pages ​

  1. Create a new .md file in the appropriate directory under docs/
  2. Add the page to the sidebar in docs/.vitepress/config.mjs:
    js
    {
  text: 'My Section',
  items: [
    { text: 'New Page', link: '/path/to/NEW_PAGE' }
  ]
}

Linking Between Pages ​

Use relative links without the .md extension:

md
See [Quick Start](../business/QUICK_START_PILOT) for details.

Adding Images ​

Place images in docs/ subdirectories (e.g., docs/screenshots/) and reference them:

md
![Screenshot](../screenshots/example.png)

Access Control ​

Make docs publicly accessible:

  1. Do NOT add Cloudflare Access policy to docs.ourlantern.app
  2. This allows anyone to view documentation
  3. Common practice for open-source projects

Option 2: Protected Docs ​

Add Cloudflare Access protection:

  1. Go to Cloudflare Zero Trust → Access → Applications
  2. Add application:
    • Domain: docs.ourlantern.app
    • Policy: One-time PIN or email authentication
  3. Repeat for docs.dev.ourlantern.app if needed

Recommendation: Keep production docs public, protect dev docs if they contain unreleased features.

Migration from /docs Path ​

What Changed ​

Before:

  • Docs built into dist/docs/ alongside main app
  • Accessed via ourlantern.app/docs/
  • VitePress base: /docs/
  • Deployed together with app

After:

  • Docs deployed separately to Cloudflare Pages
  • Accessed via docs.ourlantern.app
  • VitePress base: /
  • Independent deployment pipeline

Benefits ​

  1. Faster Updates: Update docs without rebuilding/redeploying the app
  2. Independent Scaling: Docs can scale separately from app
  3. Cleaner URLs: docs.ourlantern.app/guide vs ourlantern.app/docs/guide
  4. Better SEO: Separate subdomain is more discoverable
  5. Reduced Build Time: App builds faster without docs

Quick Reference ​

Commands ​

bash
# Development
npm run docs:dev          # Start dev server with hot reload

# Building
npm run docs:build        # Build for production

# Preview
npm run docs:preview      # Preview production build locally

URLs ​

EnvironmentURL
Productionhttps://docs.ourlantern.app
Developmenthttps://docs.dev.ourlantern.app
Local Devhttp://localhost:5173
Local Previewhttp://localhost:4173

Cloudflare Projects ​

ProjectBranchDomain
lantern-docsmaindocs.ourlantern.app
lantern-docs-devdevdocs.dev.ourlantern.app

Resources ​

Built with VitePress

Copyright © 2026 Lantern