Docs

Active contributors: Lauris, Carlos, Joe

Purpose

apps/docs is the public documentation site at developer.cal.com (and equivalent). It is built with MintLify, which renders MDX content into a polished docs experience with built-in search, API reference rendering, and versioned navigation.

Directory layout

apps/docs/
├── app/                    # MintLify Next.js shell
├── content/                # MDX docs (the source of truth for the docs site)
├── public/                 # Images, OG cards, downloads
├── fonts/
├── mdx-components.ts       # Custom MDX component overrides
├── next-env.d.ts
├── next.config.mjs
├── package.json
└── tsconfig.json

Most of the value is in apps/docs/content/. Notable subdirectories:

• apps/docs/content/api-reference/v2/openapi.json — the OpenAPI spec generated by apps/api/v2's Swagger setup. MintLify renders this as the v2 REST reference. It is one of the most-changed files in the repo (top 10 churn last 90 days), because every new endpoint regenerates it.
• apps/docs/content/platform/ — Platform / atoms documentation
• apps/docs/content/self-hosting/ — self-hosting guide
• apps/docs/content/api-keys/ — API key creation walkthrough

How it works

MintLify ingests the content/ directory at build time and produces a static documentation site. Custom MDX components (callouts, code-with-tabs, OpenAPI inline blocks) are declared in apps/docs/mdx-components.ts.

The OpenAPI rendering uses MintLify's <RequestExample> / <ResponseExample> components plus the openapi.json shipped in content/api-reference/v2/.

Integration points

• API v2 — Whenever someone adds a controller in apps/api/v2, the Swagger decorators feed apps/api/v2/src/swagger/ which writes the OpenAPI spec consumed by this app.
• GitHub Actions — there is a docs build job in .github/workflows/all-checks.yml that ensures the MintLify build succeeds before merge.

Entry points for modification

• Add a guide: drop a new .mdx file under apps/docs/content/<area>/ and register it in MintLify's nav (configured in the MintLify config, currently bundled with the package).
• Update API reference: the v2 reference is regenerated from code; the v1/legacy reference and conceptual docs can be edited as MDX directly.
• Customize rendering: edit apps/docs/mdx-components.ts.

Related pages

• API v2 — generates the OpenAPI spec the docs render
• API overview