Global settings
Your entire documentation experience is driven by a single JSON file located at /docs/config.json. It behaves like a centralized docs.json: flip tokens, navigation, and feature flags in one place and Vellocs regenerates every route.
config.json ships with the build, so avoid storing secrets. Treat it as the public blueprint for your site.
Setting up config.json
You only need a handful of fields to get started: name, url, theme.layout, one color, and at least one navigation path. Everything else is optional.
Schema autocomplete
Add the $schema property at the top of config.json to unlock IDE hints:
The schema matches the types exported from config/docs.ts so validation errors in your editor will mirror runtime expectations.
Reference
Every property below is optional unless otherwise noted. Nesting follows dot-notation (for example colors.background).
Customization
Display name for your documentation site. Appears in metadata, navigation, and footers.
Base URL of your documentation site (e.g., https://docs.example.com). Used for generating sitemaps, canonical URLs, and SEO metadata. Must start with http:// or https://.
Short description used for SEO and social previews when a page omits its own description.
Layout preset. default shows a top navbar plus sidebar, atlas removes the top navbar, and horizon adds the pill-style search bar plus section dividers.
Controls light/dark switching behaviour.
Default color mode. Choose system to respect the user's OS preference.
When true, hides the mode toggle and locks the interface to the default.
Pass any Shiki theme name to change syntax highlighting for inline and fenced code blocks.
Hex values for every design token. These map directly to CSS variables generated by lib/config.ts and ultimately to Tailwind utilities.
Logo configuration. If you pass a string it will be treated as a static image path. Passing an object lets you define light/dark variations plus fallback text.
Relative path to your site's favicon. Place assets under /public so that next export can find them.
Optional overrides for body, heading, and code text. Each section accepts a Google Fonts family name plus an optional weight.
Structure & navigation
Configure the header-level links and primary call-to-action.
Each entry requires a label and href. Links render to the right of the tab navigation.
Highlighted action button. Supported type values: button (label + URL) or github (renders a GitHub icon plus repo link).
Defines every page the router can reach. Paths never include the /docs/ prefix or .mdx extension—reference guides/foo for /docs/guides/foo.mdx.
Overrides layout defaults for navigation behaviour. Set true to force automatic navigation to the first page whenever a group expands, or false to only expand/collapse without navigating.
Content experience
Optional site-wide announcement bar. Accepts text, optional href + linkText, icon, variant (default, info, warning, success, rainbow), iconBackground, dismissible, and a unique id for persistence.
Footer & socials
Configure the footer layout.
Hide the footer entirely (useful for one-pagers).
Map of platform keys (github, x, discord, linkedin, youtube) to URLs. Used for icon buttons.
Columnar link lists. Each section defines a header and items array with label + href pairs.
SEO & metadata
Controls search engine indexing and LLM crawler behavior.
Controls which URLs appear in the generated sitemap and robots.txt. navigable only indexes links present in navigation, all indexes every MDX file, and none disables indexing entirely.
Enable generation of /sitemap.xml. Set to false to disable sitemap generation.
Enable generation of /robots.txt. Set to false to disable robots.txt generation.
Enable generation of /llms.txt, a summary of your documentation structure for LLM crawlers. Set to false to disable.
Customize per-status error pages.
Automatically send users to the homepage instead of showing the 404 screen.