The Mintlify docs site

Besides the VitePress site in website/, the documentation can be published with Mintlify, which gives a site in the style of the big developer docs (top tabs, search, an API reference made from the OpenAPI spec). The pages are still written here, in docs/*.md: the Mintlify project in mintlify/ is generated from them and committed, because Mintlify deploys straight from the repository.

How the site is made

node scripts/build-mintlify.js (no dependencies) reads docs/ and writes mintlify/:

On the way the Markdown is made safe for MDX: <, { and } outside code are escaped, HTML comments become MDX comments, <https://…> autolinks become links, links to other pages lose their .md (/guides/first-run), links to files outside docs/ go to GitHub, > [!NOTE] / > **Tip:** blocks become <Note> / <Tip> / <Warning> callouts, and the VitePress <div class="tl-…"> blocks become <Columns> and <Card>s. docs/flash/ and docs/index.html are left out (they are pages of the VitePress site).

Three files in mintlify/ are written by hand and never overwritten: index.mdx (the landing page), custom.css (small style touches) and openapi.json (the API reference's spec, made by scripts/gen-openapi.js).

The tabs and groups live in the NAV list at the top of the script, and each page's icon and short sidebar name in META. A new page in docs/ that isn't listed there still shows up, under Guides → More.

After changing anything in docs/, run the script again and commit mintlify/ with it:

node scripts/build-mintlify.js           # rewrite mintlify/
node scripts/build-mintlify.js --check   # what CI runs: fails if mintlify/ is out of date
node scripts/build-mintlify.js --check --mermaid   # also compiles every Mermaid diagram (needs mmdc)

--check also checks the site: every page in the navigation exists and every page is in it, every internal link points at a page (and a heading on it), every image exists, nothing MDX can't read is left outside code, and docs.json has the shape of Mintlify's schema.

The docs website at tempolight.pages.dev/docs

The same mintlify/ project is also built into a static website without Mintlify, by node scripts/build-docs-site.js (no dependencies; the renderer is in scripts/docs-site/). Cloudflare Pages runs it as part of node scripts/build-site.js, so every push to main publishes it at tempolight.pages.dev/docs next to the online demo.

• Pages: the tabs, groups, icons, colours and logos come from docs.json; the MDX pages are rendered by a small Markdown + MDX renderer that knows the Mintlify components the pages use (cards and columns, callouts, steps, tabs, code groups, accordions, frames, fields). Mermaid diagrams are drawn in the browser by the official Mermaid build from jsDelivr (a pinned version), in the site's dark or light colours.
• API reference: openapi.json becomes an overview, a page per tag and a page per operation (parameters, request body and responses with their fields, code samples in curl, JavaScript and Python, the example responses) under /docs/api-reference/. Each operation has a Try it panel that sends the request from the browser. Tempolight refuses requests from other websites, so it works only after turning on Integrations → Docs site → Let the docs site try API calls (admin only, off by default; see Security); the panel says so and shows the same request as a curl command.
• Search: a JSON index of every page, heading and API operation, searched in the browser (Ctrl+K, ⌘K or /).
• Icons: Lucide's (ISC licence), only the ones used, copied into scripts/docs-site/icons.js by node scripts/docs-site/gen-icons.js <a clone of github.com/lucide-icons/lucide>; run it after using a new icon.

node scripts/build-docs-site.js --serve   # build and serve it at http://localhost:3000/docs/
node scripts/e2e-docs.js                  # the browser test CI runs (needs Playwright)

Preview it on Mintlify

With Node.js 20 or later:

cd mintlify
npx mint dev          # http://localhost:3000
npx mint broken-links # Mintlify's own link check

Deploy it

Once, by the owner of the GitHub repository:

1. Go to mintlify.com/start and sign up with GitHub.
2. Name the project tempolight: the name is the subdomain, so the site will be at https://tempolight.mintlify.site (pick another name if that one is taken).
3. When it asks for the repository, connect GitHub, choose D4RKGEEK/tempolight, branch main, and install the Mintlify GitHub App (choose Only select repositories, then tempolight). Later this is in the dashboard under Git settings.
4. In Git settings, turn on docs.json is in a subdirectory (the monorepo setting) and enter /mintlify as the path, without a slash at the end. Saving starts a deployment from that folder.
5. Optional, a custom domain such as docs.example.com: in Custom domain setup, add the domain, then add the two TXT records it shows at your DNS provider, and once both show a green check, the CNAME record (to cname.mintlify.builders). The HTTPS certificate comes by itself.

From then on every push to main that changes mintlify/ redeploys the site, and pull requests get a preview at tempolight-<branch>.mintlify.site from the GitHub App.