SGLang Documentation Migration Plan

Background

Migrate the new Mintlify-based documentation (currently in the standalone sgl-docs repo) into the sglang main repo under docs_new/, and point staging.docs.sglang.io to it.

Current State

• Cookbook is already inside sgl-docs/cookbook/, no separate repo needed.
• Old docs CI (execute-notebook.yml, lint.yml) only watches docs/**, will not be triggered by docs_new/**.

Phase 1: Git Subtree Merge (Local Experiment)

Goal: Merge sgl-docs into sglang repo's docs_new/ directory, preserving full commit history and authorship.

# 1. Create a new branch (sglang remote is NOT affected)
cd /path/to/sglang
git checkout -b docs-new-migration

# 2. Add sgl-docs as a remote (sgl-docs repo is NOT affected, read-only fetch)
git remote add sgl-docs [email protected]:sgl-project/sgl-docs.git
git fetch sgl-docs

# 3. Subtree merge — all sgl-docs content goes into docs_new/, full history preserved
git subtree add --prefix=docs_new sgl-docs main

# 4. Keep the remote for ongoing sync during migration period
#    (remove only after sgl-docs is officially archived)

Safety Guarantees

• sgl-docs original repo: unaffected (fetch only, no push)
• sglang remote: unaffected (local branch, no push until ready)
• Rollback: git checkout main && git branch -D docs-new-migration

Side Effect: Contributors

git subtree add (without --squash) imports all original commits. Authors from sgl-docs will appear in sglang's git history and GitHub Contributors list. This is intentional — it gives proper credit.

Phase 2: Configure Mintlify for docs_new/ (on branch)

Goal: Make Mintlify read from sglang repo's docs_new/ subdirectory instead of the standalone sgl-docs repo. No need to merge to main first — Mintlify can point to a specific branch for validation.

1. Log in to Mintlify Dashboard
2. Change the project's GitHub repository from sgl-project/sgl-docs to sgl-project/sglang
3. Set Branch to docs-new-migration (temporarily, for validation)
4. Set Documentation directory to docs_new (Mintlify supports monorepo subdirectory)
5. docs.json (Mintlify config) will be at docs_new/docs.json after the subtree merge — paths inside it (e.g., cookbook/llm/Qwen/Qwen3) are relative to docs_new/, so no changes needed
6. Verify the preview build succeeds on Mintlify

Phase 3: DNS & Custom Domain for staging.docs.sglang.io

Goal: Make staging.docs.sglang.io serve the new Mintlify docs.

1. DNS: Add a CNAME record for staging.docs.sglang.io pointing to Mintlify's endpoint (typically cname.mintlify.dev)
2. Mintlify Dashboard: Settings > Custom Domain > add staging.docs.sglang.io
3. Mintlify handles SSL certificate automatically
4. Verify staging.docs.sglang.io loads correctly

Phase 4: Ongoing Sync During Migration Period

During the transition, sgl-docs may still receive updates. Sync them into docs_new/ as needed.

# Pull latest changes from sgl-docs into docs_new/
git subtree pull --prefix=docs_new sgl-docs main

Once sgl-docs is frozen, this step is no longer needed.

Phase 5: CI/CD (Optional, Post-Migration)

Current docs/** CI workflows will NOT trigger for docs_new/** changes. This is fine initially since Mintlify has its own GitHub integration for auto-deployment on push to main.

Optional additions later:

• Link checking (lychee) for docs_new/**/*.mdx
• Mintlify broken-link or build validation on PR

Phase 6: Final Cutover

Goal: Promote staging to production.

Cutover steps:

1. Confirm staging.docs.sglang.io is stable and content-complete
2. Update DNS: point docs.sglang.io CNAME from GitHub Pages to Mintlify (cname.mintlify.dev)
3. Update Mintlify Dashboard custom domain to docs.sglang.io
4. Remove or archive old resources:
   • Delete sglang/docs/ (old Sphinx docs)
   • Delete .github/workflows/release-docs.yml and .github/workflows/execute-notebook.yml
   • Archive sgl-project/sgl-docs repo on GitHub
   • Remove the sgl-docs git remote: git remote remove sgl-docs
   • Optionally archive sgl-project/sgl-project.github.io repo

Execution Order

Mintlify supports pointing to a specific branch, so we can validate on docs-new-migration before merging to main.