Lantern

Appearance

Documentation Subdomain Migration - Q&A ​

This document answers your questions about moving docs to docs.ourlantern.app.

Q: Should we move the /docs site to a subdomain of docs.ourlantern.app? ​

Answer: YES, and it's now implemented! ✅

Why it's a good idea:

  1. Faster docs updates - You can update documentation without rebuilding or redeploying the entire app
  2. Independent scaling - Docs can scale separately from the app
  3. Cleaner URLs - docs.ourlantern.app/guide is cleaner than ourlantern.app/docs/guide
  4. Better SEO - Search engines treat subdomains as separate entities, improving discoverability
  5. Reduced app build time - The main app builds faster without including docs
  6. Preview deployments - You can preview docs changes in PRs before merging

What's been done:

✅ VitePress configuration updated to serve from subdomain root
✅ GitHub Actions workflow created for automatic deployment
✅ Separate Cloudflare Pages configuration prepared
✅ Comprehensive setup documentation created
✅ Build process separated (app and docs build independently)

Q: How do I set it up in Cloudflare? ​

Answer: Follow the step-by-step checklist in CLOUDFLARE_DOCS_SETUP.md

Quick overview:

  1. Create two Cloudflare Pages projects:

    • lantern-docs (production, connected to main branch)
    • lantern-docs-dev (development, connected to dev branch)

  2. Configure custom domains:

    • docs.ourlantern.app → lantern-docs project
    • docs.dev.ourlantern.app → lantern-docs-dev project

  3. Add GitHub repository secrets:

    • CLOUDFLARE_API_TOKEN - API token with "Edit Cloudflare Workers" permission
    • CLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID

  4. Test the deployment:

    • Push a change to dev branch
    • Watch GitHub Actions run
    • Visit docs.dev.ourlantern.app to verify

Detailed guides:

  • Setup checklist: CLOUDFLARE_DOCS_SETUP.md
  • Deployment guide: DOCS_DEPLOYMENT.md
  • Workflow docs: .github/workflows/README.md

Q: What happens if I push to dev or prod? ​

Answer: Automatic deployment to the appropriate environment!

When you push to dev branch: ​

1. GitHub detects push to dev branch
2. GitHub Actions workflow triggers (deploy-docs.yml)
3. Workflow checks if docs files changed
4. Installs dependencies (npm ci)
5. Builds VitePress site (npm run docs:build)
6. Deploys to lantern-docs-dev Cloudflare Pages project
7. Site is live at docs.dev.ourlantern.app in ~2-3 minutes

Workflow triggers when:

  • You push commits to dev branch
  • Any file in docs/ directory changed
  • package.json or package-lock.json changed (dependency updates)
  • The workflow file itself changed

When you push to main (production): ​

1. GitHub detects push to main branch
2. GitHub Actions workflow triggers
3. Builds and deploys to lantern-docs project
4. Site is live at docs.ourlantern.app in ~2-3 minutes

Same triggers as dev, but deploys to production subdomain.

When you open a Pull Request: ​

1. GitHub Actions creates a preview deployment
2. Preview URL: https://feature-xyz.lantern-docs-dev.pages.dev
3. You can review docs changes before merging
4. Preview updates on each push to the PR branch

Q: How can we make sure that the docs are actually updated? ​

Answer: Multiple verification methods built in!

1. GitHub Actions Status ​

In GitHub:

  • Go to the Actions tab in your repository
  • Click on Deploy Documentation workflow
  • See status of recent deployments (green = success, red = failure)
  • Click on a run to see detailed logs

What to look for:

  • ✅ "Build documentation" step succeeds
  • ✅ "Publish to Cloudflare Pages" step completes
  • ✅ "Deployment summary" shows the correct URL

2. Cloudflare Pages Dashboard ​

In Cloudflare:

  • Go to Workers & Pages → Pages
  • Select lantern-docs or lantern-docs-dev
  • View Deployments tab
  • See deployment history with timestamps

What to look for:

  • Latest deployment timestamp matches your push time
  • Deployment status shows "Success"
  • Build logs show no errors

3. Browser Verification ​

Visit the site:

  • Production: https://docs.ourlantern.app
  • Development: https://docs.dev.ourlantern.app

How to ensure you see latest changes:

  1. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
  2. Check the page content matches your changes
  3. Use browser DevTools → Network tab → disable cache

4. Git Commit Hash ​

For advanced verification:

The deployment includes the git commit hash. You can verify:

  1. Note your commit SHA from git log
  2. Check GitHub Actions run - it shows the commit
  3. Check Cloudflare Pages deployment - shows same commit
  4. They should match!

5. Automated Deployment Summary ​

The GitHub Actions workflow creates a summary showing:

  • Branch deployed
  • Environment (production/development)
  • Project name
  • URL where it's deployed

Check this in the workflow run's "Summary" section.

Troubleshooting: Docs Not Updating ​

Problem: Pushed changes but docs look the same ​

Cause 1: Browser cache

  • Solution: Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
  • Or: Open in incognito/private window

Cause 2: Workflow didn't trigger

  • Solution: Check GitHub Actions tab
  • Verify files you changed are in docs/ directory
  • Ensure you pushed to the correct branch

Cause 3: Build failed

  • Solution: Check GitHub Actions logs for errors
  • Common issues: markdown syntax errors, broken links

Cause 4: Wrong branch deployed

  • Solution: Verify you pushed to dev or main, not a feature branch
  • Feature branches deploy to preview URLs, not the main subdomain

Cause 5: Cloudflare cache

  • Solution: Go to Cloudflare Pages → Deployments → "Retry deployment"
  • Or wait 5 minutes for cache to clear

Quick Reference ​

Files Changed in This PR ​

  • .github/workflows/deploy-docs.yml - Automatic deployment workflow
  • docs/.vitepress/config.mjs - Updated base path from /docs/ to /
  • wrangler.docs.toml - Cloudflare Pages configuration for docs
  • scripts/build-all.sh - Separated app and docs builds
  • DOCS_DEPLOYMENT.md - Comprehensive deployment guide
  • CLOUDFLARE_DOCS_SETUP.md - Step-by-step setup checklist
  • README.md - Updated with new docs URLs

Commands ​

bash
# Build docs locally
npm run docs:build

# Preview docs locally
npm run docs:dev      # Development server
npm run docs:preview  # Preview production build

# Deploy docs (automatic on push)
git push origin dev   # Deploys to docs.dev.ourlantern.app
git push origin main  # Deploys to docs.ourlantern.app

URLs ​

EnvironmentURLUpdates on push to
Productionhttps://docs.ourlantern.appmain branch
Developmenthttps://docs.dev.ourlantern.appdev branch
PR Previewhttps://feature-xyz.lantern-docs-dev.pages.devPull requests

Next Steps ​

  1. Complete Cloudflare setup (follow CLOUDFLARE_DOCS_SETUP.md)
  2. Add GitHub secrets (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID)
  3. Test deployment by pushing a small change to dev
  4. Verify docs appear at docs.dev.ourlantern.app
  5. Decide on access control (public vs protected - see setup guide)
  6. Update any external links to point to new docs subdomain

Summary ​

Yes, moving docs to a subdomain is a great idea and is now ready to deploy!

Setup: Follow the checklist in CLOUDFLARE_DOCS_SETUP.md - takes about 15 minutes.

On push: Automatic deployment to the correct subdomain (dev or prod) via GitHub Actions.

Verification: Check GitHub Actions status, Cloudflare dashboard, or visit the URL directly.

Benefits: Faster updates, cleaner URLs, independent scaling, better SEO, preview deployments.

Questions? Check the detailed guides in DOCS_DEPLOYMENT.md or open an issue!

Built with VitePress

Copyright © 2026 Lantern