Mintlify-Like Docs Publishing with Codex

Use this guide to generate docs locally with Codex and publish them to your handle site on 10x.in using a scoped PAT, with optional JWT fallback when your workspace still relies on the control-plane deployment route.

When to use

You want Mintlify-style structure (docs.json navigation) but host docs on your own 10x handle site.
You want a local generation flow plus API publish to https://{handle}.10x.in/docs.
You want repeatable deploy commands that Codex can run for you.

Prerequisites

Your handle already exists (example: links).
You have a PAT_TOKEN with site.deployments.write.
Optional but recommended: a valid creator JWT_TOKEN for fallback during rollout or scope troubleshooting.
Docs source files are in docs/external.
Every page you want published is listed in docs/external/docs.json.

Codex workflow (recommended)

Ask Codex to create or update markdown pages in docs/external/....
Ask Codex to add page keys to docs/external/docs.json navigation.
Ask Codex to run a dry run publish.
Review the summary output (file count, bytes, missing pages).
Ask Codex to run live publish and activation.
Verify live URLs.

Command: dry run

PAT_TOKEN="YOUR_PAT_TOKEN" \
HANDLE="links" \
DRY_RUN=1 \
npm run site:publish:external-docs

Command: live publish

PAT_TOKEN="YOUR_PAT_TOKEN" \
JWT_TOKEN="YOUR_OPTIONAL_JWT_TOKEN" \
HANDLE="links" \
API_BASE_URL="https://ai.10x.in" \
ACTIVATE=1 \
VERIFY=1 \
DRY_RUN=0 \
npm run site:publish:external-docs

If API_BASE_URL is omitted, the production default is https://ai.10x.in.

Output URL pattern

Docs root: https://{handle}.10x.in/docs
Page route: https://{handle}.10x.in/docs/<page-route>
SEO artifacts:
https://{handle}.10x.in/docs/sitemap.xml
https://{handle}.10x.in/docs/llms.txt
https://{handle}.10x.in/robots.txt

Required auth

Preferred: PAT_TOKEN with site.deployments.write.
Optional fallback: creator-level bearer JWT in JWT_TOKEN.
Do not commit tokens to git, docs, or scripts.
Rotate token if exposed.

API fallback

If you need to implement outside the script:

POST /v2/public/handles/{handle}/site-deployments with PAT_TOKEN to create the draft deployment.
Upload each file to returned pre-signed putUrl
POST /v2/public/handles/{handle}/site-deployments with:

{
  "activate": true,
  "deploymentId": "dep_xxx"
}

If your environment still requires the control-plane deployment route, use the same request body against POST /v2/handles/{handle}/site-deployments with JWT_TOKEN.

Common errors

Status	Error	Fix
401	`Unauthorized`	Check that `PAT_TOKEN` is valid for the target handle. If you are using fallback, refresh `JWT_TOKEN` too.
403	`insufficient_scope`	Add `site.deployments.write` to the PAT, or provide `JWT_TOKEN` so the script can fall back.
400	`missing_entrypoint`	Ensure `index.html` is in deployment manifest (script handles this).
Script failure	Missing markdown source	Add missing page file or remove page from `docs.json`.
Verify failure	Route returns `404`	Confirm page key exists in `docs.json` and was included in upload.