site.yaml reference

Field-by-field reference for site configuration.

Config file at the docs sync root: site.yaml or site.yml. Parsed as YAML on each git sync. Invalid YAML is ignored (treated as empty config); prefer validating locally before merge.

Site metadata

title: Acme Docs
visibility: public
theme:
  accent_color: '#0F766E'
  logo_url: https://cdn.example.com/logo.svg
  layout: centered
exclude:
  - README.md
  - '**/drafts/**'
navbar_links:
  - text: GitHub
    url: https://github.com/acme/docs
    type: minimal
sections: []

Key	Type	Required	Notes
`title`	string	No	Site title in the header
`visibility`	string	No	`public` \| `private`
`theme`	object	No	Branding and content layout
`nav`	object	No	Advanced; `navbar_links` writes `nav.links`
`exclude`	string[]	No	Skip during Markdown discovery
`navbar_links`	array	No	Right-aligned header actions
`sections`	array	No	When set, full section rebuild on sync
`accent_color`	string	No	Legacy; prefer `theme.accent_color`
`logo_url`	string	No	Legacy; prefer `theme.logo_url`

theme

theme:
  accent_color: '#0F766E'
  logo_url: https://cdn.example.com/logo-light.svg
  logo_dark_url: https://cdn.example.com/logo-dark.svg
  favicon_url: https://cdn.example.com/favicon.ico
  layout: centered

Key	Type	Aliases	Default	Notes
`accent_color`	string	`accent`	Site / product default	Brand accent for interactive chrome
`logo_url`	string	`logo`	unset (no logo)	Absolute URL; light or single logo
`logo_dark_url`	string	`logo_dark`, `dark_logo`	unset	Absolute URL; used in dark mode when set
`favicon_url`	string	`favicon`	unset (app default)	Absolute URL for the tab icon
`layout`	string	—	`full`	`full` \| `centered`

layout

Value	Sidebars	Guide article	Header bar
`full`	Viewport edges	Readable width, centered	Full bleed
`centered`	Shared centered column (~88rem)	Same column	Full bleed; inner content matches column

Other theme keys (typography, backgrounds, CSS) are not applied yet — see Customization.

navbar_links[]

navbar_links:
  - text: GitHub
    url: https://github.com/acme/docs
    type: minimal
  - text: Dashboard
    url: https://app.example.com
    type: filled

Key	Type	Aliases	Default	Notes
`text`	string	`label`	—	Button label
`url`	string	`href`	—	Absolute or site-relative
`type`	string	`style`	`minimal`	`minimal` \| `filled` \| `outlined`

Stored on the site as nav.links.

exclude

List of globs or path fragments matched against paths relative to the sync root (and again per section after merging section exclude).

Examples:

exclude:
  - README.md
  - README.mdx
  - '**/drafts/**'
  - internal.md

Matching is case-insensitive for simple basenames; glob patterns support * and ** style paths as implemented by the importer.

sections[]

When present, sync deletes and recreates all sections and guide pages from this list. Empty or invalid lists that produce zero sections fail validation.

Each item is one of the kinds below. Items with children are groups.

Guide section

- name: Guide
  slug: guide
  path: .
  icon: book-open
  exclude:
    - README.md
  pages:           # optional
    - introduction.md
    - get-started/quickstart.md

Key	Type	Required	Notes
`name`	string	Yes*	Top-nav label (`*` defaults to `Section` if missing)
`slug`	string	No	Default `guide` when omitted in guide branch
`icon`	string	No	Emoji, short text, or Lucide name for the header tab
`path`	string	No	Relative directory; `.` or empty → sync root
`exclude`	string[]	No	Merged with site `exclude`
`pages`	string[]	No	Explicit files relative to `path`; order preserved

Discovery rules when pages is omitted:

Include *.md / *.mdx under path
Exclude matches
Sort: position → shallower path → path string
Directories → sidebar folders
Zero pages → sync error

API embed

- name: API
  slug: api
  api: payments
  icon: code
  api_layout:
    tag_order: [Pets, Users]
    hide_tags: [Internal]
    hide_operations:
      - GET /health
    hide_models: false
    flatten: false

Key	Type	Notes
`api`	string	Organization API id or slug
`slug`	string	Default `api`
`icon`	string	Optional header tab icon
`api_layout`	object	Optional nav customization — see API reference layout

SDK embed

- name: SDKs
  slug: sdks
  sdk: payments-sdk

Key	Type	Notes
`sdk`	string	SDK id, slug, or name (slug preferred)
`slug`	string	Default `sdks`

CLI embed

- name: CLI
  slug: cli
  cli: payments-cli

Key	Type	Notes
`cli`	string	CLI id or name
`slug`	string	Default `cli`

Unresolved embed refs fail sync with a clear validation message.

Group

- name: More
  slug: more          # optional; parent is not routable
  children:
    - name: SDKs
      slug: sdks
      sdk: payments-sdk

Key	Type	Notes
`name`	string	Dropdown label
`children`	array	Nested section defs (guides or embeds)
`slug`	string	Allocated for uniqueness; parent has no page URL

Slug allocation

Section slugs are slugified from slug or name. Collisions get numeric suffixes (guide-2, …). Page slug collisions within a section fail sync — fix with unique frontmatter slug values or different paths.

Link rewriting

On import, relative Markdown hrefs resolve against the file’s directory and map to /{sectionSlug}/{pageSlug} when the target was imported. Unmapped relative targets keep a best-effort path without .md.