Skip to main content

​
Mintlify Directory

This directory contains the documentation frontend powered by Mintlify. It renders the OpenAPI specification from Spec/ into a user-facing API reference website.

​
Layout

  • docs.json — Mintlify site configuration (navigation, theme, metadata)
  • api-reference/ — Bundled OpenAPI spec consumed by Mintlify (bundled.yaml)
  • *.mdx (at this directory’s root) — Custom documentation pages. Each file maps 1:1 to a URL (getting-started.mdx → /getting-started).
  • icons/ — Custom icon assets
  • scripts/ — Post-bundle transforms (see below)
  • Dockerfile — Container setup for the documentation site

​
Key Files

  • api-reference/bundled.yaml — The bundled OpenAPI spec; regenerate with npm run bundle from the repo root
  • *.mdx — Additional hand-written documentation pages beyond the auto-generated API reference

​
Workflow

  1. Edit the source specification in Spec/
  2. Run npm run bundle to produce the bundled spec
  3. The bundled output lands in api-reference/bundled.yaml and Mintlify renders it

​
Post-bundle transforms

Spec/’s npm run bundle runs redocly bundle and then chains node ../Mintlify/scripts/apply-coming-soon.js bundled.yaml.
  • scripts/apply-tag-hierarchy.js — reads the OpenAPI 3.2 tag hierarchy (kind: nav sections + parent: on endpoint tags), rewrites the API Documentation group in docs.json into one nested group per section, then downgrades the bundle to 3.1 and strips the section tags and the parent/kind/summary fields — Mintlify supports 3.0/3.1 only and rejects those fields. It also badges any group whose operations are all x-new with tag: "NEW", which is why it runs before apply-new.js (that script strips the flags). Delete this script when Mintlify supports 3.2; the spec is already correct.
  • scripts/apply-coming-soon.js — for every operation flagged x-coming-soon: <timing> in Spec/paths/, prepends a Mintlify <Warning> callout to the operation description and strips the flag from the bundled output. The flag value is the release-timing phrase, interpolated into the banner sentence. Delete the script and the flags wholesale at GA.