Schema reference

For an introduction to the file and how it fits into a deploy, see docs.json overview.

Full example

A docs.json with every field populated. Copy this and trim what you don't need.

{
  "name": "Acme docs",
  "description": "Documentation for Acme.",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg",
    "href": "https://acme.com"
  },
  "favicon": "/favicon.png",
  "navigation": [
    {
      "tab": "Guide",
      "groups": [
        {
          "group": "Get started",
          "pages": ["quickstart", "introduction"]
        },
        {
          "group": "Configuration",
          "pages": ["configuration/docs-json", "configuration/theme"]
        }
      ]
    },
    {
      "group": "Reference",
      "pages": ["reference/schema"]
    },
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ],
  "navbar": [
    { "name": "GitHub", "url": "https://github.com/acme/docs" },
    { "name": "Support", "url": "mailto:support@acme.com" }
  ],
  "theme": {
    "preset": "ocean",
    "primaryOverride": "oklch(0.62 0.19 145)"
  },
  "api": {
    "playground": {
      "display": "interactive"
    }
  }
}

Top-level fields

All nine fields are optional. A docs.json with {} is valid and renders the site with default name, no sidebar, no navbar links, and the unstyled fallback palette.

name

Site title. Used as the navbar brand text, the browser tab title, and the OpenGraph title for link previews.

{ "name": "Acme docs" }

description

One-sentence summary of the site. Used as the meta description and the OpenGraph description for link previews and search results.

{ "description": "Documentation for Acme." }

logo

Brand image shown in the top-left of the navbar, in place of the site name. Paths resolve from your repo root. See Logo and favicon.

Logo object

{ "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg" } }

favicon

Icon shown in the browser tab. Takes the same shorthand and object forms as logo, without href.

{ "favicon": "/favicon.png" }

languages

Languages the site serves. Adding a second code turns on the language switcher and the per-language content folders. See Internationalization.

English (en) is always the default language. Other codes are served under a URL prefix (/es/...).

{ "languages": ["en", "es"] }

navigation

Sidebar entries. An array of items, each either a group or a tab. The two shapes are mutually exclusive: a group has group and pages, a tab has tab and groups. See Navigation for ordering, labels, and hiding pages.

Group item

Provide pages, openapi, or both. A group with openapi lists its operation pages after any pages you set. See API reference overview.

{
  "group": "Get started",
  "pages": ["quickstart", "introduction"]
}

A group entry inside pages renders as a collapsible subsection. Pages in a nested group must share a folder prefix.

{
  "group": "Editor",
  "pages": [
    "editor/overview",
    {
      "group": "Components",
      "pages": ["editor/components/accordion", "editor/components/callout"]
    },
    "editor/images"
  ]
}

Tab item

{
  "tab": "API reference",
  "groups": [{ "group": "Endpoints", "pages": ["api/endpoints/create"] }]
}

navbar

External links shown in the top navigation bar. See Navbar.

Navbar item

{
  "navbar": [
    { "name": "GitHub", "url": "https://github.com/acme/docs" },
    { "name": "Dashboard", "url": "https://app.acme.com", "variant": "primary" }
  ]
}

theme

Color palette for the site. See Theme for previews and dark mode behavior.

Theme fields

{
  "theme": {
    "preset": "default",
    "primaryOverride": "#10b981"
  }
}

theme.primaryOverride

A string sets the light-mode color, and Bloques derives the dark-mode shade from it. The object form sets each mode.

Bloques converts the string form and light to oklch(), drops any transparency, and adjusts lightness until the color reaches a contrast ratio of at least 3:1 against its background. A dark value renders as written.

{
  "theme": {
    "primaryOverride": {
      "light": "#0f172a",
      "dark": "#7aa2f7"
    }
  }
}

api

Settings for pages generated from an OpenAPI spec. See API reference overview.

api.playground

Controls the request panel at the top of every generated endpoint page.

Parameters, request and response schemas, and code samples render in every mode. Only the live-request panel changes.

{
  "api": {
    "playground": {
      "display": "simple"
    }
  }
}

api.playground.proxy

Send routes through Bloques by default, so your API doesn't need to allow cross-origin requests (CORS) from your docs domain.

Set proxy to false to send from the reader's browser instead. Do that when your API authenticates the browser itself — mutual TLS, a client certificate, an IP allowlist — or when you'd rather reader-supplied keys never reach our servers. Your API then has to allow CORS from your docs domain.

{
  "api": {
    "playground": {
      "proxy": false
    }
  }
}

Some servers are called straight from the browser either way, because Bloques can't safely proxy them: a localhost or private-network address, a plain http:// URL, or a server URL with a free-form variable in its hostname.

Validation

Bloques validates docs.json on every deploy. An invalid file fails the deploy and the site keeps serving the last good version. Common failures:

A missing or invalid openapi spec doesn't fail the deploy. Bloques skips it and the rest of the site builds. See Set up an API reference for troubleshooting.