Skip to content
Blode.md

AI agents: fetch the documentation index at llms.txt. Markdown versions are available by appending .md to any page URL, including this page's markdown.

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.

Minimal example

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

Branded example

{
  "$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

FieldTypeDescriptionRequired
$schemastringJSON Schema URL for editor autocomplete. Use `https://blode.md/docs.json`.Yes
namestringDisplay name for your site, project, or organization.Yes
slugstringRecommended URL-safe project slug used for deployments and the default `{slug}.blode.md` hostname.Yes
descriptionstringShort project description used in metadata and SEO.Yes
logostring | { light, dark, alt?, href? }Logo shown in the header. Accepts a single path or `{ light, dark, alt?, href? }`.Yes
faviconstring | { light, dark }Browser tab icon. Accepts a single path or `{ light, dark }`.Yes
appearanceobjectLight and dark mode settings. Set `default` to `dark`, `light`, or `system`. Use `strict` to lock the site mode.Yes
navbarobjectHeader links shown above your content.Yes
navigationobjectSidebar and tab structure. Defines the hierarchy of your pages. See [Navigation](/configuration/navigation).Yes
apiobjectAPI reference configuration for OpenAPI and AsyncAPI sources plus playground settings.Yes
contextualobjectContextual action buttons shown on each page, such as copy, view source, or assistant shortcuts.Yes
searchobjectSearch configuration.Yes
seoobjectSearch engine indexing settings.Yes
metadataobjectMetadata configuration.Yes

Branding fields

FieldTypeDescriptionRequired
logo.lightstringLogo path for light mode.Yes
logo.darkstringLogo path for dark mode.Yes
logo.altstringAccessible alt text for the logo image.Yes
logo.hrefstringOptional destination when someone clicks the logo. Defaults to the docs homepage.Yes
favicon.lightstringFavicon path for light mode.Yes
favicon.darkstringFavicon path for dark mode.Yes
appearance.default'system' | 'light' | 'dark'Initial color mode. Defaults to `system`.Yes
appearance.strictbooleanWhen `true`, hides the mode toggle and locks the site to the selected default mode.Yes

API reference

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

FieldTypeDescriptionRequired
api.openapistring | string[] | OpenApiSourcePath to your OpenAPI spec. Accepts a string, array of strings, or a source object with `source`, `basePath`, `directory`, and `include`.Yes
api.asyncapistring | string[] | OpenApiSourcePath 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

Contextual actions

FieldTypeDescriptionRequired
contextual.display'header' | 'toc'Where to render the action buttons.Yes
contextual.optionsArray<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

Validation is strict: an unknown key is an error, so a typo like nvaigation fails before it ships rather than silently doing nothing.

A published site is served leniently. If a deployed docs.json contains a key the platform does not recognise — because it was written for a newer version, or a field was retired — the site keeps rendering and the key is ignored. Only genuine problems, like a navigation tree of the wrong shape, stop a page from being served. Your docs never go down because of a config key.