docs.json overview

Define your site's name, navigation, and theme in a single config file.

What docs.json does

docs.json is the contract between your repo and your rendered site. Whatever you set here drives the sidebar, navbar, theme, and site metadata. Edit docs.json, push, and the site reflects the change on the next deploy.

Where it lives

Place docs.json at the root of your docs directory. Bloques reads it on every deploy, and changes take effect on the next push.

Minimal example

The smallest valid config sets a name, a description, one navigation group with one page, and a theme preset.

{
  "name": "Acme docs",
  "description": "Documentation for Acme.",
  "navigation": [{ "group": "Get started", "pages": ["quickstart"] }],
  "theme": { "preset": "default" }
}

Page paths in navigation are repo-relative and omit the .mdx extension. The example above points to quickstart.mdx at the root of your docs directory.

What's in docs.json

Four top-level fields shape the site:

• Navigation — groups, tabs, and page ordering.
• Theme — preset and primary color override.
• Navbar — external links in the top bar.
• Schema reference — every field, in one place.

Validation

Bloques validates docs.json on every deploy. An invalid config surfaces in the deploy logs and prevents the site from updating, so the live site keeps serving the last good version. See Deployments for how a deploy runs end to end.