Branding

Before you begin

• A docs.page project with docs.json at the repository root and page files under docs/
• Install the CLI or use npx @docs.page/cli; see Preview to check theme, logo, header, and footer changes before you push
• Logo and favicon files committed under docs/ (or hosted at stable URLs) when you plan custom assets

Theme settings control typography, accent colors, and how the site looks in light and dark mode. Pick a shadcn preset for a cohesive palette, then override individual tokens with hex colors when you need brand-specific accents.

For how presets, fonts, and mode switching work, see Theme. Field names and defaults live in docs.json.

• Choose a preset or set custom colors

  Add a theme object at the top level of docs.json. Include preset when you want a shadcn palette, or omit it and set color keys directly:

  "theme": {
    "preset": "bcj0c6sa",
    "primary": "#E69135"
  }

• Preview light and dark mode

  Run Preview and toggle the theme control in the header. Confirm accents and backgrounds look right in both modes before you push.

The schema accepts defaultTheme (light or dark) to pin the starting mode, but that field is schema only today; see docs.json: Schema-only fields.

Header logos and tab icons support separate light and dark assets. Use one variant when a single mark works everywhere, or pair variants so each mode stays legible.

{
  "logo": {
    "light": "/assets/logo-light.svg",
    "dark": "/assets/logo-dark.svg"
  },
  "favicon": "/assets/favicon.png"
}

Place repo-relative paths under docs/, for example /assets/logo-light.svg resolves to docs/assets/logo-light.svg. See Logo for URL shapes, legacy v1 migration, and how favicon media queries differ from the site theme toggle.

The header shows identity on the left and actions on the right: search, custom links, GitHub, and the theme toggle. Control whether the site name appears beside the logo and add CTA buttons with header.links.

• Tune identity and add header links

  Set header.showName to false when the logo alone carries your wordmark. Add header.links with title, href, and optional cta: true for a filled button:

  "header": {
    "showName": false,
    "links": [
      { "title": "Changelog", "href": "/changelog" },
      { "title": "Get started", "href": "https://app.example.com/signup", "cta": true }
    ]
  }

• Preview the bar on a few page types

  Open the homepage and an inner page in preview. Confirm link order, CTA styling, and logo alignment.

The schema also defines showThemeToggle and showGitHubCard, plus optional locale on each link; the header renderer does not apply those fields yet. The theme toggle and GitHub link always render on hosted sites today. See Header.

When your sidebar outgrows one tree, define top-level tabs in the header and scope sidebar groups to each tab's id.

"tabs": [
  { "id": "docs", "title": "Documentation", "href": "/" },
  { "id": "features", "title": "Features", "href": "/features" }
]

Tag each sidebar group with "tab": "docs" (or another tab id). Groups without tab appear on every tab. See Navigation tabs for URL-based active tab resolution and Organize when you restructure navigation.

Footer icons link to your profiles on every page. Values are handles or path fragments, not full URLs (except website):

{
  "social": {
    "website": "https://acme.dev",
    "github": "acme",
    "discord": "acme-community"
  },
  "og": {
    "github": true
  }
}

Set og.logo or top-level socialPreview when share cards need artwork beyond your header logo. See Social links for supported platforms and preview image resolution.

1. Run Preview and toggle light and dark mode; confirm logo, colors, and favicon behave as expected.
2. Open the homepage and at least one inner page; check header links, tabs (if configured), and footer icons.
3. Paste a docs URL into a chat app or inspect meta tags; confirm title, description, and preview image look right when sharing.