docs.json reference

Complete reference for the docs.json configuration file.

Every Blode.md project is configured through a single docs.json file at the root of your docs directory. This page covers every top-level field.

Minimal example

{
  "$schema": "https://mintlify.com/docs.json",
  "name": "my-project",
  "theme": "mint",
  "colors": { "primary": "#0D9373" },
  "navigation": {
    "groups": [{ "group": "Getting started", "pages": ["index"] }]
  }
}

Full example

{
  "$schema": "https://mintlify.com/docs.json",
  "name": "my-project",
  "theme": "mint",
  "description": "Documentation for my product.",
  "colors": {
    "primary": "#0D9373",
    "light": "#CFF6EE",
    "dark": "#0C3A33"
  },
  "logo": {
    "light": "/images/logo-light.svg",
    "dark"

Top-level fields

Field	Type	Description	Required
`$schema`	string	JSON Schema URL for editor autocomplete. Use `https://mintlify.com/docs.json`.	Yes
`name`	string	Project slug. Determines your `*.blode.md` subdomain and acts as the project identifier.	Yes
`theme`	string	Visual theme for your documentation site.	Yes
`description`	string	Short project description used in metadata and SEO.	Yes
`colors`	object	Brand colors for the site. Only `primary` is required. See [Theming](/configuration/theming).

The navbar object configures the top navigation bar.

Field	Type	Description	Required
`navbar.links`	Array<{ label: string, href: string }>	Array of link objects displayed in the navbar.	Yes
`navbar.primary`	{ type: 'button' \| 'discord' \| 'github', label?: string, href: string }	Primary CTA button in the navbar.	Yes

API reference

The api object controls OpenAPI/AsyncAPI rendering and the API playground.

Field	Type	Description	Required
`api.openapi`	string \| string[] \| OpenApiSource	Path to your OpenAPI spec. Accepts a string, array of strings, or a source object with `source`, `basePath`, `directory`, and `include`.	Yes
`api.asyncapi`	string \| string[] \| OpenApiSource	Path to your AsyncAPI spec. Same format as `openapi`.	Yes
`api.playground`	{ display?: 'auth' \| 'interactive' \| 'none' \| 'simple', proxy?: boolean, credentials?: boolean }	API playground settings.	Yes
`api.examples`	{ autogenerate?: boolean, defaults?: 'all' \| 'required', languages?: string[], prefill?: boolean }	Code example generation settings.	Yes
`api.params`

Contextual actions

The contextual object adds action buttons to each page, letting readers copy content, open it in AI assistants, or perform custom actions.

Field	Type	Description	Required
`contextual.display`	'header' \| 'toc'	Where to render the action buttons.	Yes
`contextual.options`	Array<string \| CustomOption>	Array of built-in presets or custom action objects.	Yes

Built-in option presets: copy, view, chatgpt, claude, perplexity, grok, aistudio, cursor, vscode, windsurf, devin, mcp, add-mcp, devin-mcp, assistant.

Validation

Run blodemd validate to check your docs.json against the schema before deploying:

blodemd validate

Navigation -- configure sidebar groups, tabs, and page ordering
Theming and branding -- customize colors, logos, fonts, and appearance

docs.json reference

Minimal example

Full example

Top-level fields

Navbar

API reference

Contextual actions

Validation

Minimal example

Full example

Top-level fields

Navbar

API reference

Contextual actions

Validation

docs.json reference

Minimal example

Full example

Top-level fields

Navbar

API reference

Contextual actions

Validation

Related pages

Minimal example

Full example

Top-level fields

Navbar

API reference

Contextual actions

Validation

Related pages