Configuration

docs.json is optional and lives at the root of the folder named by DOCS_DIR. It extends supported Mintlify fields. Unknown fields produce diagnostics; a malformed known field falls back independently. Unparseable JSON and unsafe or invalid content can fail the build.

Files and titlesCopy Anchor Link

index.mdx becomes its directory’s landing page. Other .md and .mdx files become paths based on their filenames. A title comes from frontmatter, then the first Markdown H1, then the filename. For example:

# Quickstart

Follow these steps to make a request.

Use meta.json to order a directory’s sidebar entries. "..." includes remaining pages:

{ "title": "Guides", "pages": ["index", "quickstart", "..."] }

An explicit navigation block in docs.json controls the sidebar. Pages left out of it can still be reached by URL; hiding a page is not access control. Do not put confidential content in a public documentation tree.

Site configurationCopy Anchor Link

{
  "name": "Example Docs",
  "theme": "aspen",
  "colors": { "primary": "#2563EB" },
  "navigation": {
    "groups": [{ "group": "Start", "pages": ["index", "quickstart"] }]
  },
  "x-margin": {
    "search": { "mode": "static" },
    "layout": { "sidebarWidth": "300px" }
  }
}

Mintlify themes map to framework-owned layout presets. They approximate the upstream layout rather than reproduce it pixel for pixel. Colors, logos, fonts, navigation, OpenAPI references, redirects, and supported analytics settings remain data. Local snippet components can add executable page content, but they do not replace server code or the configuration schema.

Framework extensionsCopy Anchor Link

The vendor namespace is x-margin. Common settings include:

These fields belong inside x-margin; for example, x-margin.search.mode. Server modules selected by DOCS_EXTENSIONS use a separate TypeScript contract.

Product versionsCopy Anchor Link

Product versions such as v1 and v2 are path partitions inside one content snapshot. They are separate from deployment versions keyed by commit. Directory conventions or explicit navigation can define them. A version root’s meta.json can label it and choose a default:

{ "title": "Version 2", "x-margin-version": "v2", "x-margin-version-default": true }

Assets and stylingCopy Anchor Link

Keep images, logos, and fonts inside the docs folder. Ingest rewrites admitted asset references to content-addressed URLs. SVGs are sanitized; CSS is parsed and sanitized before serving. Stylesheets cannot introduce arbitrary scripts. Inter and Geist Mono are the bundled text fonts; OG cards use Geist Sans.

IconsCopy Anchor Link

Builds use the MIT-licensed Hugeicons Free set. To use a licensed Hugeicons Pro set, set HUGEICONS_PRO_TOKEN in the build environment, optionally choose HUGEICONS_PRO_STYLE, then run bun run icons:build or redeploy. The script fetches Pro into a temporary directory; it is never a manifest dependency. A missing content glyph falls back to the default icon; a missing chrome glyph fails the build. Never commit the token, the Pro package, or generated Pro SVGs. Your Pro license governs deployment and redistribution.

Environment variablesCopy Anchor Link

Outside Vercel, only the database URL and SITE_ORIGIN are required. Empty strings count as unset. Keep secrets in your environment or Vercel project, never in docs.json or a committed environment file.

The deployment standard defines the supported field inventory, precedence, and MDX security contract; see also deployment and extensions.