Photon Docs

The documentation site at photon.codes, built with Mintlify and driven by vellum. Vellum extracts type information from installed npm packages and renders .mdx.vel templates into the .mdx files Mintlify ships.

This repo is an aggregator: some doc areas are authored here in docs-src/, and others are authored in the SDK repos they document and pulled in at build time (see Where docs live).

Where docs live

scripts/sync-docs assembles a single template tree (.vellum-src/, gitignored) before vellum runs, from two places:

• Local — most areas still live in docs-src/ in this repo.
• Source repos — areas listed in scripts/sources.json are pulled from their SDK repo's configured docs directory, at the configured git ref. For Spectrum, that is photon-hq/spectrum-ts main and the docs/ directory, so prose fixes can ship without an SDK release. Vellum still extracts types from the installed package versions in this repo, so source-repo docs must stay compatible with the released package. Edit those docs in the SDK repo, not here. Local builds can use the local fallback in the manifest, but CI and deploy use DOCS_SOURCE_MODE=git.

Navigation works the same way: docs.json is generated by scripts/build-nav from docs.base.json (the site skeleton) plus a nav.json fragment contributed by each source. A source can route selected subdirectories to separate mounts, so it can own pages such as /integrations/* and /best-practices/* without changing their public URLs. Don't edit docs.json directly — edit docs.base.json or the fragment.

How to edit

1. Edit the source, not the output. Sources are .mdx.vel files in docs-src/ (this repo) or the source repo docs directory configured in scripts/sources.json. The rendered .mdx files and docs.json at the repo root are build artifacts — gitignored on main, only present on the dist branch. Don't edit them directly; they get overwritten on every deploy.

2. Render and preview locally:

   pnpm install
   pnpm docs:generate         # vellum: .mdx.vel -> .mdx
   mint dev                   # preview at http://localhost:3000

   If you don't have the Mintlify CLI: npm i -g mint.

3. Verify before opening a PR:

   pnpm lint
   pnpm typecheck:docs

4. Open the PR against main. Don't commit rendered .mdx files — they're regenerated by CI.

How deployment works

Push to main → .github/workflows/deploy-dist.yml runs pnpm docs:generate and force-pushes the rendered tree to the dist branch → Mintlify rebuilds from dist.

The Spectrum API reference is generated from a remote OpenAPI spec configured in docs.json, fetched at build time, so every rebuild picks up the latest API surface without a docs commit.

Source-repo doc updates can also trigger deploy through repository_dispatch type spectrum-ts-docs. Use that when photon-hq/spectrum-ts changes docs/** without a package release.

Auto-updates from SDK releases

When a connected SDK ships a release (e.g., spectrum-ts, advanced-imessage-ts), its release workflow calls photon-hq/buildspace/.github/workflows/update-docs.yaml. That workflow uses Claude Code to draft a docs/update-{sdk}-v{version} PR here, bumping the package so Vellum extracts the new released types. Older PRs for the same SDK are auto-closed by .github/workflows/close-stale-version-prs.yml.

For docs-only edits in a source repo, merge the change to the source repo's main branch and dispatch spectrum-ts-docs here. Do not cut a package release just to fix prose.

To enroll a new SDK, add .github/workflows/update-docs.yaml to its repo following the pattern in advanced-imessage-ts.

Troubleshooting

• mint dev shows 404s: make sure you're running it at the repo root where docs.json lives, and that pnpm docs:generate completed without errors first.
• CLI behaves oddly: mint update.
• OpenAPI looks stale on the live site: trigger the docs rebuild so Mintlify re-fetches the spec — push any commit to main, or fire the repository_dispatch from the relevant backend release.