Skip to main content

​
Current structure

docs.json defines three tabs:
  1. Guides – landing page, quickstart, workflow, and writing practices.
  2. Engineering – AI tooling playbooks (Cursor, Claude Code, Windsurf).
  3. API reference – App Launch + health endpoints wired to OpenAPI.
Each group entry in docs.json looks like this: 
{
  "group": "Mobile app",
  "pages": [
    "api-reference/endpoint/app-launch",
    "api-reference/endpoint/app-health"
  ]
}
You don’t include .mdx in the path—Mintlify resolves it automatically.

​
Adding a page

  1. Create the MDX file under docs/ (e.g. docs/runbooks/incident.mdx).
  2. Update docs.json and add the relative path runbooks/incident.
  3. Run mint dev to verify the sidebar shows the new entry.

​
Best practices

  • Keep groups short (3–4 pages). Spin up a new group if you need more.
  • Use verbs or outcomes in group names (“Operate”, “Observe”, “Secure”) instead of vague buckets like “Misc”.
  • Link to GitHub markdown (implementation notes, RFCs) from the relevant pages instead of duplicating content inside the docs site.

​
Hidden / utility pages

Any MDX file that is not referenced in docs.json is “hidden”—Mintlify can still render it when accessed by URL, but it won’t show up in the sidebar. Use this for drafts, experiment logs, or short-lived release notes.