links.arjun.tv/docs/end-user/mintlify-like-docs-publishing-with-codex

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 JWT token.

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}.{PUBLIC_DOMAIN}/docs.
  • You want repeatable deploy commands that Codex can run for you.

Prerequisites

  1. Your handle already exists (example: links).
  2. You have a valid creator JWT token.
  3. Docs source files are in docs/external.
  4. Every page you want published is listed in docs/external/docs.json.

Codex workflow (recommended)

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

Command: dry run

JWT_TOKEN="YOUR_JWT_TOKEN" \
HANDLE="links" \
DRY_RUN=1 \
npm run site:publish:external-docs

Command: live publish

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

Output URL pattern

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

Required auth

  • 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/handles/{handle}/site-deployments (create draft with manifest)
  2. Upload each file to returned pre-signed putUrl
  3. POST /v2/handles/{handle}/site-deployments with:
{
  "activate": true,
  "deploymentId": "dep_xxx"
}

Common errors

StatusErrorFix
401UnauthorizedUse a fresh creator token and correct handle ownership.
400missing_entrypointEnsure index.html is in deployment manifest (script handles this).
Script failureMissing markdown sourceAdd missing page file or remove page from docs.json.
Verify failureRoute returns 404Confirm page key exists in docs.json and was included in upload.

Related: