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

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

Repository structure

Use this structure when adding or refreshing public documentation:

For feature launches, update the feature guide, add or move the page in the matching manifest, add a landing-page card when the feature should be discoverable from the first screen, and run a dry run before live activation.

Current handle split

Codex workflow (recommended)

1. Ask Codex to create or update markdown pages in docs/external/....
2. Ask Codex to place each page in the right manifest: product, developer, or examples.
3. Ask Codex to run a dry run publish for every affected handle.
4. Review the summary output (file count, bytes, missing pages).
5. Ask Codex to run live publish and activation for each affected handle.
6. Verify live URLs.

Command: dry run

PAT_TOKEN="YOUR_PAT_TOKEN" \
HANDLE="links" \
DOCS_JSON_PATH="docs/external/docs.json" \
SEO_CONFIG_PATH="docs/external/seo.config.json" \
DRY_RUN=1 \
npm run site:publish:external-docs

Change HANDLE, DOCS_JSON_PATH, and SEO_CONFIG_PATH together when deploying developers or examples.

Command: live publish

PAT_TOKEN="YOUR_PAT_TOKEN" \
JWT_TOKEN="YOUR_OPTIONAL_JWT_TOKEN" \
HANDLE="links" \
DOCS_JSON_PATH="docs/external/docs.json" \
SEO_CONFIG_PATH="docs/external/seo.config.json" \
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:

1. POST /v2/public/handles/{handle}/site-deployments with PAT_TOKEN to create the draft deployment.
2. Upload each file to returned pre-signed putUrl
3. 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.

Important for MCP-assisted publishing:

• site_deploy_multifile can fully deploy in one MCP call when you provide file content for all text files.
• If you omit content, it falls back to returning upload URLs for manual upload flow.
• Use site_release_get_files before asking the model to edit an already deployed site.
• Use site_release_rollback to restore an older release after a bad publish.
• Do not substitute PUT /v2/handles/{handle}/site-mode for deployment activation.

Common errors

Related:

• API Tokens and Automations
• API Auth and Error Model
• Troubleshooting and Support