mintlify-preview

name: mintlify-preview description: Run the public Mintlify product docs site locally for live preview. Use when previewing or iterating on docs under `docs/` (`.mdx`/`.md` pages, `docs.json` nav), or when the user says "start the docs", "run mintlify", "preview the docs site". license: MIT compatibility: opencode

Mintlify docs local preview

The public product docs site lives in docs/ (docs.json + topical .mdx/.md pages). It is served locally with the Mintlify CLI (mint dev). This is the product docs site, not dev-docs/ — for durable internal domain docs see the docs skill.

TL;DR — start the server

Run from the docs/ directory (where docs.json lives), on a non-default port so it doesn't collide with the web app on 3000:

cd docs
PATH="$(ls -d "$HOME"/.nvm/versions/node/v22.*/bin 2>/dev/null | sort -V | tail -1):$PATH" mint dev --port 3333

Then open http://localhost:3333. A page at docs/<folder>/<file>.mdx is served at http://localhost:3333/<folder>/<file> (e.g. docs/monitors/overview.mdx → /monitors/overview). The server hot-reloads on edits to any .mdx/.md or docs.json.

Prefer running it in the background and tailing the output until you see ✓ preview ready.

Why the `PATH` prefix (node version gotcha)

Mintlify does not run on Node 25+. This repo's default/active Node is often 25, which fails with:

erro mintlify is not supported on node versions 25+ (current version 25.9.0).

The PATH=... prefix above pins an installed Node 22 LTS (from nvm) for just this command, without changing the repo's active Node. If no v22.* is installed, install one (nvm install 22) or use any LTS <25. mise/nvm activate in a child shell won't help — prefix the PATH on the command itself.

Keep the CLI current (schema gotcha)

docs.json uses current Mintlify schema features (e.g. styling.codeblocks as an object). An outdated CLI rejects valid config with:

🚨 Invalid docs.json: #.styling.codeblocks: Expected ... received 'object'

Fix by updating the CLI, not by editing docs.json (the checked-in config is correct for the real deploy):

PATH="$(ls -d "$HOME"/.nvm/versions/node/v22.*/bin 2>/dev/null | sort -V | tail -1):$PATH" mint update

The mint and legacy mintlify binaries can live under different Node versions and update independently. Update the same binary you run mint dev with (i.e. under Node 22).

Verify it's up

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3333/        # 307 redirect to first page — fine
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3333/monitors/overview   # 200 = page resolves

Rules

Never edit docs.json to satisfy a stale local CLI. Update the CLI instead.
Add new pages to the nav in docs.json (the navigation.groups[].pages arrays). A .mdx file that isn't referenced there won't appear in the sidebar.
Use port 3333 (or any free port ≠ 3000) so the docs server and the web dev server can run together.
<Frame>/<img> blocks pointing at missing docs/images/... files render as broken-image placeholders — expected until the assets land.