Skip to main content

​
Putting docs.layerx1.com live

One-time runbook for standing this Mintlify site up on its own domain. Everything here is done once, in the Mintlify dashboard and your DNS provider — there is no CI job and no deploy secret in this repo.
The ordering constraint that matters. apps/web/next.config.ts 308-redirects /docs/* → https://docs.layerx1.com/*. A 308 is permanent, and browsers cache permanent redirects indefinitely — surviving a revert. So docs.layerx1.com must already serve a 200 before this branch merges. Steps 1–5 below happen first; step 6 is the merge. Do not reorder them.

​
1. Connect the repo

  1. Sign in at mintlify.com with the account that should own the docs, and create a project (or open the existing one).
  2. Install the Mintlify GitHub App and grant it access to ATOM00blue/layerx1.
  3. In project settings, set:
    • Repository → ATOM00blue/layerx1
    • Deployment branch → main
    • Content directory → apps/docs
The content directory is the part people miss. This is a monorepo; without it Mintlify looks for docs.json at the repo root and finds nothing.

​
2. Deploy from this branch first (preview)

Merging is step 6, so verify the build before then. Either:
  • Open a PR from claude/host-ocs-mintify-fasg6g — the GitHub App comments a preview URL on it — or
  • Temporarily point the project’s deployment branch at claude/host-ocs-mintify-fasg6g, deploy, confirm, then set it back to main.
Click through the preview: sidebar groups render, code tabs work, the model table is populated, and /api/agent-runs and /guides/vision exist.

​
3. Add the custom domain

In Mintlify → Settings → Custom domain, enter docs.layerx1.com. Mintlify shows the DNS record to create.

​
4. Create the DNS record

layerx1.com is on Vercel, so add the record wherever the zone is authoritative (Vercel DNS if the nameservers point there, otherwise your registrar): Notes:
  • Do not proxy this record if the zone sits behind Cloudflare (grey cloud, not orange). Mintlify terminates its own TLS.
  • The apex and www are untouched. This adds one subdomain and takes nothing away.
  • Propagation is usually minutes. Certificate issuance can take a little longer; Mintlify’s domain panel shows the state.

​
5. Verify before merging

All three must pass:
If any of these is not a 200, stop — merging now writes a permanent redirect to a dead host into every visitor’s browser cache.

​
6. Merge

Merge claude/host-ocs-mintify-fasg6g into main. Two things happen on that merge:
  • Vercel rebuilds apps/web, and /docs/* starts 308-redirecting to the docs site.
  • Mintlify builds apps/docs from main and publishes it.
Then confirm the redirect chain end to end:
Two old URLs also changed path, and are handled by a second hop from docs.json redirects rather than by next.config.ts:

​
7. After it is live

  • Search Console — add docs.layerx1.com as a property and submit https://docs.layerx1.com/sitemap.xml. Existing /docs/* rankings transfer through the 308, but the new host needs its own property to be reported on.
  • Analytics — Mintlify → Settings → Integrations if you want traffic in the same place as the marketing site.
  • Check the links out — the navbar, footer and CTA all point back at https://layerx1.com/.... They are absolute because that is a different origin now.

​
Day-to-day, once live

CI runs check, mint validate and mint broken-links on every PR (.github/workflows/ci.yml, job docs-check). Mintlify publishes on merge to main — nothing to trigger by hand.

​
Rolling back

The docs site and the redirect are independent, which is what makes this safe:
  • Docs content bad → revert the docs commit; Mintlify republishes from main.
  • Redirect needs to come off → remove the two /docs rules from apps/web/next.config.ts and redeploy. Note that browsers which already cached the 308 will keep following it, which is exactly why step 5 exists.