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 the transforms below, in order.
  • 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 — or whole section — whose operations all carry the same label, with tag: "NEW", tag: "CS" or tag: "BREAKING", which is why it runs before Spec/scripts/apply-labels.js (that script strips the flags). Delete this script when Mintlify supports 3.2; the spec is already correct.
  • Spec/scripts/apply-labels.js — expands the three endpoint labels, then strips the flags and the internal x-pr / x-jira / x-change-summary tags that ride with them: x-coming-soon becomes a <Warning> callout plus a CS sidebar pill, x-new: "<date>" becomes a <Tip> callout plus a NEW pill, x-breaking-change becomes a <Danger> callout carrying its x-change-summary plus a BREAKING pill, which style.css draws as an orange-red lightning bolt (an SVG mask, not the ⚡ emoji) on a red pill. The pills are x-mint: metadata: tag:, which Mintlify reads as frontmatter for the generated endpoint page. Lives under Spec/ with the rest of the spec tooling — JavaScript under Mintlify/ is ingested as page content and served to readers. See Spec/scripts/labels.js for the value grammars.