> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blode.md/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# docs.json reference

Configure navigation, branding, and runtime behavior with docs.json.

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

> [!INFO]
> 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

```json title="docs.json"
{
  "$schema": "https://blode.md/docs.json",
  "name": "My Project",
  "slug": "my-project",
  "navigation": {
    "groups": [{ "group": "Getting started", "pages": ["index"] }]
  }
}
```

## Branded example

```json title="docs.json"
{
  "$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" }
}
```

## Top-level fields

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

## Branding fields

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

## API reference

The `api` object controls OpenAPI and AsyncAPI rendering plus playground behavior.

- `api.openapi` (type: string | string[] | OpenApiSource): Path to your OpenAPI spec. Accepts a string, array of strings, or a source object with `source`, `basePath`, `directory`, and `include`.
- `api.asyncapi` (type: string | string[] | OpenApiSource): Path to your AsyncAPI spec. Same format as `openapi`.
- `api.playground` (type: { display?: 'auth' | 'interactive' | 'none' | 'simple', proxy?: boolean, credentials?: boolean }): API playground settings.
- `api.examples` (type: { autogenerate?: boolean, defaults?: 'all' | 'required', languages?: string[], prefill?: boolean }): Autogenerated code example settings.
- `api.params` (type: { expanded?: 'all' | 'closed' }): Parameter display settings.
- `api.mdx` (type: { auth?: { method, name }, server?: string | string[] }): MDX API page settings.
- `api.url` (type: 'full'): URL display mode for endpoint headers.

## Contextual actions

- `contextual.display` (type: 'header' | 'toc'): Where to render the action buttons.
- `contextual.options` (type: Array<string | CustomOption>): Array of built-in presets or custom action objects.

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:

```bash
blodemd validate
```

## Related pages

- [Navigation](/configuration/navigation) -- configure sidebar groups, tabs, and page ordering
- [Appearance and branding](/configuration/theming) -- configure logo, favicon, and color mode behavior