Deployment

Build

ppnpm install --frozen-lockfile
pnpm build

Every page, the search index, llms.txt and the Markdown copies are generated during the build. So is the API reference: a build reads each spec's source, so a spec whose source is a ~/ path, or a URL the build cannot reach, needs a committed cache to build on Vercel, in CI or in Docker. See API reference generation. next.config.ts sets output: "standalone", so .next/standalone holds a minimal server.

Container

The Dockerfile has the same shape as the homepage image: Node 24, a non-root user, and a health check. The health check calls /docs, because every route lives there.

docker build -t hexel-docs .
docker run --rm -p 3000:3000 hexel-docs

Serving at hexelstudio.com/docs

The site sets basePath: "/docs", so its pages and its scripts and styles are all under /docs. That lets the homepage send one path prefix to this app without clashing with its own /_next files.

Today the homepage sends /docs to Mintlify. Point the same rewrite at this app instead:

async rewrites() {
  return [
    {
      source: "/docs/:path*",
      destination: `${process.env.DOCS_ORIGIN}/docs/:path*`,
    },
  ]
},

:path* also matches /docs itself, so the landing page, every page, search.json, llms.txt, the .md copies and all assets go through this one rule.

Before switching over

1. Move the pages

   Copy the Mintlify .mdx files into content/docs, keeping their paths, and paste the navigation.tabs block from docs.json into docs.config.ts.

2. Build

   pnpm build names any listed page without a file and any component the site does not provide.

3. Compare

   Open each page next to its Mintlify version. Links that start with /docs keep working, since the URLs are the same.