docs.json reference

Reference every supported docs.json field for navigation, branding, collections, OpenAPI, analytics, and deployment settings in your Blode.md project.

Every Blode.md project is configured through a single docs.json file at the root of your docs directory.

If you are coming from Mintlify, Blode.md intentionally keeps this contract smaller. theme, colors, fonts, icons, background, and styling are not supported in docs.json.

Minimal example


{
  "$schema": "https://blode.md/docs.json",
  "name": "My Project",

Published with Blode.md

docs.json reference · Blode.md


{
  "$schema": "https://blode.md/docs.json",
  "name": "My Project",
  "slug": "my-project",
  "description": "Documentation for my product.",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg",
    "alt": "Example Co. logo",
    "href": "/"
  },
  "favicon": "/favicon.svg",
  "appearance": { "default": "system" },
  "navbar": {
    "links": [{ "label": "GitHub", "href": "https://github.com/example/docs" }]
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          { "group": "Getting started", "pages": ["index", "quickstart"] }
        ]
      }
    ]
  },
  "contextual": {
    "options": ["copy", "view", "chatgpt", "claude"]
  },
  "api": {
    "openapi": "openapi.yaml",
    "playground": { "display": "interactive" }
  },
  "seo": { "indexing": "all" }
}

Field	Type	Description	Required
`$schema`	string	JSON Schema URL for editor autocomplete. Use `https://blode.md/docs.json`.	Yes
`name`	string	Display name for your site, project, or organization.	Yes
`slug`	string	Recommended URL-safe project slug used for deployments and the default `{slug}.blode.md` hostname.	Yes
`description`	string	Short project description used in metadata and SEO.	Yes
`logo`	string \| { light, dark, alt?, href? }	Logo shown in the header. Accepts a single path or `{ light, dark, alt?, href? }`.	Yes
`favicon`	string \| { light, dark }	Browser tab icon. Accepts a single path or `{ light, dark }`.	Yes
`appearance`	object	Light and dark mode settings. Set `default` to `dark`, `light`, or `system`. Use `strict` to lock the site mode.	Yes
`navbar`	object	Header links shown above your content.	Yes
`navigation`	object	Sidebar and tab structure. Defines the hierarchy of your pages. See [Navigation](/configuration/navigation).	Yes
`api`	object	API reference configuration for OpenAPI and AsyncAPI sources plus playground settings.	Yes
`contextual`	object	Contextual action buttons shown on each page, such as copy, view source, or assistant shortcuts.	Yes
`search`	object	Search configuration.	Yes
`seo`	object	Search engine indexing settings.	Yes
`metadata`	object	Metadata configuration.	Yes

Field	Type	Description	Required
`logo.light`	string	Logo path for light mode.	Yes
`logo.dark`	string	Logo path for dark mode.	Yes
`logo.alt`	string	Accessible alt text for the logo image.	Yes
`logo.href`	string	Optional destination when someone clicks the logo. Defaults to the docs homepage.	Yes
`favicon.light`	string	Favicon path for light mode.	Yes
`favicon.dark`	string	Favicon path for dark mode.	Yes
`appearance.default`	'system' \| 'light' \| 'dark'	Initial color mode. Defaults to `system`.	Yes
`appearance.strict`	boolean	When `true`, hides the mode toggle and locks the site to the selected default mode.	Yes

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 }	Autogenerated code example settings.	Yes
`api.params`	{ expanded?: 'all' \| 'closed' }	Parameter display settings.	Yes
`api.mdx`	{ auth?: { method, name }, server?: string \| string[] }	MDX API page settings.	Yes
`api.url`	'full'	URL display mode for endpoint headers.	Yes

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

docs.json reference

Minimal example

docs.json reference

Minimal example

Branded example

Top-level fields

Branding fields

API reference

Contextual actions

Validation

docs.json reference

Minimal example

docs.json reference

Minimal example

Branded example

Top-level fields

Branding fields

API reference

Contextual actions

Validation

Related pages