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:

Faster docs updates - You can update documentation without rebuilding or redeploying the entire app
Independent scaling - Docs can scale separately from the app
Cleaner URLs - docs.ourlantern.app/guide is cleaner than ourlantern.app/docs/guide
Better SEO - Search engines treat subdomains as separate entities, improving discoverability
Reduced app build time - The main app builds faster without including docs
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:

Create two Cloudflare Pages projects:
- lantern-docs (production, connected to main branch)
- lantern-docs-dev (development, connected to dev branch)
Configure custom domains:
- docs.ourlantern.app → lantern-docs project
- docs.dev.ourlantern.app → lantern-docs-dev project
Add GitHub repository secrets:
- CLOUDFLARE_API_TOKEN - API token with "Edit Cloudflare Workers" permission
- CLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID
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:

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

4. Git Commit Hash

For advanced verification:

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

Note your commit SHA from git log
Check GitHub Actions run - it shows the commit
Check Cloudflare Pages deployment - shows same commit
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

Environment	URL	Updates on push to
Production	https://docs.ourlantern.app	`main` branch
Development	https://docs.dev.ourlantern.app	`dev` branch
PR Preview	https://feature-xyz.lantern-docs-dev.pages.dev	Pull requests

Next Steps

Complete Cloudflare setup (follow CLOUDFLARE_DOCS_SETUP.md)
Add GitHub secrets (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID)
Test deployment by pushing a small change to dev
Verify docs appear at docs.dev.ourlantern.app
Decide on access control (public vs protected - see setup guide)
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!

Documentation Subdomain Migration - Q&A ​

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

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

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

When you push to dev branch: ​

When you push to main (production): ​

When you open a Pull Request: ​

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

1. GitHub Actions Status ​

2. Cloudflare Pages Dashboard ​

3. Browser Verification ​

4. Git Commit Hash ​

5. Automated Deployment Summary ​

Troubleshooting: Docs Not Updating ​

Problem: Pushed changes but docs look the same ​

Quick Reference ​

Files Changed in This PR ​

Commands ​

URLs ​

Next Steps ​

Summary ​