​

Serving Mintlify at www.keycli.com/docs

This page is a deployment plan, not a claim that the Mintlify docs are already live at that URL.

​

Current status today

What exists now:

• Mintlify source docs live in-repo under docs/
• Mintlify config lives in docs.json (primary) and mint.json (compatibility)
• the repo supports npm run docs:validate
• the marketing site has a real /docs fallback hub inside apps/site
• the marketing site now supports both redirect mode and proxy mode for docs cutover
• proxy mode covers the practical Mintlify route surface needed for a real cutover, not just /docs and /docs/:path*

What does not exist yet unless you provision it:

• a production Mintlify deployment serving public traffic
• a smoke-tested Mintlify origin ready for public cutover
• proof that the external docs origin exposes the expected auxiliary routes cleanly for your final deployment

​

Cutover controls in apps/site

The marketing app now exposes two docs cutover env vars: Notes:

• if KEYCLI_DOCS_ORIGIN is set with only an origin, the site assumes Mintlify is served from /docs
• if KEYCLI_DOCS_ORIGIN includes a path, that path is used as the docs base
• KEYCLI_DOCS_ORIGIN is server-side infrastructure, not a promise that the origin already exists
• proxy mode only turns on when NEXT_PUBLIC_DOCS_URL is the same-origin public /docs URL

​

Supported proxy route coverage

When proxy mode is enabled, the marketing site currently rewrites these public routes to the external Mintlify origin: Important non-goals / boundaries:

• site-owned root routes like /robots.txt and /sitemap.xml remain owned by the marketing app
• if the external docs origin does not expose /llms.txt or /mcp, those routes will still fail upstream; the proxy does not fake them
• this setup is for a public /docs cutover, not for making the entire marketing site a Mintlify app

​

Exact runtime behavior

​

1) No docs cutover env vars set

Recommended while the external docs deployment does not exist yet. Behavior:

• landing CTAs keep linking to /docs
• www.keycli.com/docs serves the in-app fallback hub
• sitemap includes /docs
• no external proxying is attempted

This is the honest default.

​

2) NEXT_PUBLIC_DOCS_URL points at an external deployment, KEYCLI_DOCS_ORIGIN is unset

Recommended while validating a separate docs deployment before public /docs cutover. Behavior:

• landing CTAs use the external docs URL
• visiting /docs on the marketing app redirects to that external URL
• the local hub no longer pretends it is the primary public docs surface
• public www.keycli.com/docs is not yet a Mintlify proxy in this mode

This is the right interim step when the docs deployment exists but the on-site cutover is not ready.

​

3) NEXT_PUBLIC_DOCS_URL=https://www.keycli.com/docs and KEYCLI_DOCS_ORIGIN is set

Recommended final shape once the external Mintlify deployment is stable. Behavior:

• landing CTAs keep using the public /docs URL
• Next.js rewrites the supported Mintlify public route surface before filesystem routes
• the fallback hub remains in the repo, but public traffic bypasses it
• public users stay on www.keycli.com/docs while Mintlify serves the content underneath
• root-level Mintlify auxiliary routes like /api/search, /api/request, /llms.txt, and /mcp are also routed to the docs origin

This is the actual cutover mode for serving Mintlify at the public subpath.

​

Target architecture

Use two deployments:

​

1) Marketing site deployment

• Vercel project rooted at apps/site
• owns https://www.keycli.com/
• keeps serving the landing and top-level marketing experience

​

2) Mintlify docs deployment

• separate deployment for the repo’s Mintlify docs (docs/, docs.json, mint.json)
• configured so Mintlify works correctly under /docs
• allowed to stabilize on an internal or preview origin before public cutover

This separation is still the right shape because docs and marketing will evolve at different speeds.

​

Recommended rollout

​

Phase 1 — keep Mintlify as the source of truth in-repo

Already true today:

• docs/
• docs.json
• mint.json
• npm run docs:validate

​

Phase 2 — stand up Mintlify on a non-public origin

Examples:

• Vercel preview deployment
• dedicated Vercel project URL
• Mintlify-hosted deployment URL

Goal:

• validate navigation, links, assets, and search
• validate any Mintlify root-level auxiliary routes you intend to expose publicly (/api/search, /api/request, /llms.txt, /mcp)
• prove deep-link refreshes work on the docs deployment itself
• confirm the docs build is stable before touching the main domain

​

Phase 3 — use redirect mode first if needed

Set:

• NEXT_PUBLIC_DOCS_URL=https://<preview-docs-url>/docs
• leave KEYCLI_DOCS_ORIGIN unset

This gives you a clean public handoff from the marketing site without pretending that www.keycli.com/docs is already backed by Mintlify.

​

Phase 4 — switch to proxy mode for the real cutover

Set:

• NEXT_PUBLIC_DOCS_URL=https://www.keycli.com/docs
• KEYCLI_DOCS_ORIGIN=https://<stable-docs-origin>

Then verify:

• GET /docs shows Mintlify content through the marketing app
• GET /docs/<nested-page> works directly
• hard refresh on nested pages works
• JS, CSS, images, and helper assets resolve correctly
• GET /api/search and POST /api/request resolve correctly through the marketing domain
• GET /llms.txt and GET /mcp behave as intended for the chosen docs deployment
• site-owned routes like /robots.txt and /sitemap.xml still belong to the marketing app
• canonical/indexing behavior matches the intended public rollout

​

Vercel implementation notes

​

Marketing site (apps/site)

• import the repo into Vercel
• set Root Directory to apps/site
• keep the detected Next.js framework
• add the env vars from apps/site/.env.example
• do not set KEYCLI_DOCS_ORIGIN until the docs origin is genuinely ready

​

Mintlify docs deployment

Use whatever Mintlify/Vercel setup you prefer, but the result must support the final public base path. Before enabling proxy mode, confirm all of these on the docs origin:

• docs home resolves correctly
• nested docs pages resolve correctly
• static assets load correctly
• client-side navigation works
• hard refresh works on deep links
• search / request routes work if you plan to expose them publicly
• /llms.txt and /mcp are either intentionally supported or intentionally absent
• no requests assume site root / when they should live under /docs

​

What changed in the repo

The marketing app now has lightweight docs cutover infrastructure:

• config-driven public docs routing via NEXT_PUBLIC_DOCS_URL
• config-driven external docs origin support via KEYCLI_DOCS_ORIGIN
• Next.js rewrites for the supported Mintlify route surface, not just /docs
• a fallback docs hub that stays useful when no external origin is configured
• a clean redirect path when you intentionally want to use an external docs URL first

​

Deployment checklist

Before calling this done:

• choose the concrete Mintlify docs deployment URL
• run npm run docs:validate
• run npm run landing:typecheck
• run npm run landing:build
• decide whether you are in fallback, redirect, or proxy mode
• if using redirect mode, set only NEXT_PUBLIC_DOCS_URL
• if using proxy mode, set both NEXT_PUBLIC_DOCS_URL and KEYCLI_DOCS_ORIGIN
• smoke test /docs plus at least one nested docs page
• if using proxy mode, smoke test /api/search, /api/request, /llms.txt, and /mcp as applicable for your docs deployment
• verify canonical/indexing behavior
• only then switch public navigation fully to the Mintlify-backed /docs surface

​

Recommendation

The best long-term deployment story is still:

• Mintlify for docs authoring + navigation
• Vercel for the marketing app
• subpath proxying so the public URL stays www.keycli.com/docs

But the repo now supports the honest intermediate state too: keep the fallback hub while the docs origin does not exist yet, or redirect to an external preview before the final public cutover.