Site configuration lives in docs.json or docs.yaml at the repository root. For how each area behaves, see the matching page on Features. Machine-readable schema: /schema.json.
{
"$schema": "https://docs.page/schema.json",
"name": "My project",
"description": "Documentation for My project.",
"sidebar": []
}| Field | Section |
|---|---|
name, description, socialPreview | name, description, socialPreview |
logo, favicon, banner, theme | logo, favicon, banner, theme |
header, tabs, sidebar, anchors | header, tabs, sidebar, anchors |
content, seo, variables | content, seo, variables |
redirects | redirects |
scripts, search, social, og | scripts, search, social, og |
agent, mcp | agent, mcp |
These keys validate in docs.json and appear in /schema.json, but the hosted site does not apply them yet. Setting them has no visible effect until support ships.
| Field | Validates | Applied | Workaround |
|---|---|---|---|
theme.defaultTheme | yes | no | Readers use the platform default starting mode; they can still toggle light/dark in the header |
header.showThemeToggle | yes | no | Theme toggle always renders on hosted sites |
header.showGitHubCard | yes | no | GitHub link always renders on hosted sites |
header.links[].locale | yes | no | All configured links render on every locale |
See Theme and Header for behavior that is implemented today.
Optional JSON Schema URL for editor autocompletion and validation (for example https://docs.page/schema.json). Not read by docs.page at runtime.
Site title used in the header, browser tab, and generated Open Graph images when a page has no frontmatter title.
Falls back to Documentation when omitted.
Default site description for metadata and social previews when a page has no frontmatter description.
Static Open Graph image URL applied site-wide. Set to false to disable the default generated image without setting a custom URL.
Per-page frontmatter image overrides this value. See Page frontmatter.
Logo URL for light mode. Paths are resolved relative to the repository root.
Logo URL for dark mode. When omitted, light mode logo is reused.
Favicon URL or mode-specific URLs.
"favicon": "/docs/favicon.png""favicon": {
"light": "/docs/favicon-light.png",
"dark": "/docs/favicon-dark.png"
}A string sets the same icon for both modes.
Announcement text shown in the site-wide banner strip.
Optional link target when the banner is clicked.
Banner background color.
Banner text color.
Schema only: theme.defaultTheme validates in docs.json but is not applied by the theme provider yet. See Schema-only fields.
Schema only: header.showThemeToggle, header.showGitHubCard, and header.links[].locale validate in docs.json but are not applied by the header renderer yet. Theme toggle and GitHub link always render on hosted sites. See Schema-only fields.
Top-level navigation tabs. Each tab scopes sidebar groups with a matching tab id.
Tab identifier referenced by sidebar tab fields.
Label shown in the tab bar.
Root-relative path opened when the tab is selected, usually the first page in that tab's sidebar.
When set, show this tab only for the matching locale sidebar.
See Tabs.
Navigation tree for the site. Two shapes are supported:
Flat (single locale): array of group objects:
"sidebar": [
{
"group": "Getting Started",
"pages": [{ "title": "Introduction", "href": "/" }]
}
]Locale-keyed: object with locale codes as keys (plus optional default):
"sidebar": {
"default": [{ "group": "Guide", "pages": [] }],
"fr": [{ "group": "Guide", "pages": [] }]
}Shortcut links rendered below the sidebar search box.
Font Awesome icon slug.
Link label.
Root-relative path or external URL.
Show this anchor only for the matching locale.
Show this anchor only when the active tab matches.
See Links.
When true, add noindex to every page on the site. Default: false. Per-page override: frontmatter noindex. See Search engine indexing.
Arbitrary nested object whose string leaf values are substituted into MDX bodies with {{ dotted.path }} syntax during bundling.
"variables": {
"product": "Handbook",
"api": { "baseUrl": "https://api.example.com" }
}The {{ product }} API lives at {{ api.baseUrl }}.Only string leaf values substitute. Intermediate objects are traversed; non-string leaves leave the placeholder unchanged. Variables do not apply inside frontmatter. See Global variables.
Centralized { "from": "to" } map for forwarding old URLs whose page files were removed. Keys are old root-relative doc paths; values are the destinations. Keys and values are matched tolerant of leading and trailing slashes.
"redirects": {
"/old-guide": "/guides/getting-started",
"installation/setup": "/getting-started",
"/legacy-api": "https://api.example.com/reference"
}Values may be internal root-relative paths (resolved against the current routing mode and ref, like frontmatter redirect) or external http(s):// / // URLs (returned unchanged). Each match issues a 307 Temporary Redirect.
This map is consulted only when no .mdx file exists at the requested path (a deleted or moved page). When a file is still present, its own frontmatter redirect governs instead. See Redirects.
Analytics and tag-manager injection on published pages only, not during local preview.
Google Tag Manager container ID (for example GTM-XXXX). When set, direct Google Analytics injection is skipped even if googleAnalytics is also present.
GA4 measurement ID (for example G-GXXXX). Used only when googleTagManager is not set.
Plausible analytics. Set to true for the hosted Plausible script, or a string URL for self-hosted Plausible. Requires a mapped custom domain or vanity subdomain, and is inactive on the default docs.page/{owner}/{repo} path.
See Analytics.
Footer social profile URLs. Each key is an optional URL string.
| Key | Description |
|---|---|
social.website | Project or company website |
social.x | X (Twitter) profile |
social.youtube | YouTube channel |
social.facebook | Facebook page |
social.instagram | Instagram profile |
social.linkedin | LinkedIn page |
social.github | GitHub organization or user |
social.slack | Slack community invite or workspace |
social.discord | Discord server invite |
"social": {
"github": "https://github.com/acme",
"x": "https://x.com/acme"
}See Social links.
Open Graph image generation defaults when no page or site image is set.
Logo URL embedded in auto-generated social preview images.
Include the GitHub repository name in generated preview images. Default: true.
Ask AI chat panel configuration. Beta.
Agent credential key returned by docs agent create. Required to enable the in-docs chat panel.
Placeholder text in the empty question input.
Suggested starter questions shown before the reader types.
Maximum chat requests per IP per hour. Default: 200.
Maximum chat requests per repository per hour. Default: 10000.
See Ask AI.
Expose the per-repository MCP endpoint at /{owner}/{repo}/mcp. Default: true. Set to false to return 404 on the MCP route.
See MCP server.
- Page frontmatter: per-page YAML fields
- CLI:
docs init,docs preview,docs check, agent commands - HTTP endpoints: published routes and platform APIs