Site settings

Configure title, theme, sections, and navbar links with site.yaml.

The site.yaml (or site.yml) file at your docs sync root is the primary way to configure a git-backed site. Console settings still work for sites that are not git-synced; when sections: is present on sync, YAML rebuilds the section tree.

Complete starter

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
  - text: Dashboard
    url: https://app.example.com
    type: filled
sections:
  - name: Guide
    slug: guide
    path: .
    exclude:
      - README.md
  - name: API
    slug: api
    api: payments
  - name: More
    children:
      - name: SDKs
        slug: sdks
        sdk: payments-sdk

Core fields

Field	Required	Description
`title`	No	Site title in the header
`visibility`	No	`public` or `private`
`theme`	No	Branding and layout (see below)
`exclude`	No	Globs skipped during Markdown discovery
`navbar_links`	No	Right-aligned header actions
`sections`	Recommended	Top-nav definition; when set, full section rebuild on sync
`nav`	No	Advanced nav bag; prefer `navbar_links`

Top-level accent_color and logo_url are still accepted for older configs. Prefer nesting them under theme.

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   # full (default) | centered

Key	Aliases	Notes
`accent_color`	`accent`	Brand accent in the docs shell
`logo_url`	`logo`	Absolute URL; light or single logo
`logo_dark_url`	`logo_dark`, `dark_logo`	Absolute URL used in dark mode when set
`favicon_url`	`favicon`	Absolute URL for the browser tab icon
`layout`	—	See layout semantics below

Layout semantics

Value	Behavior
`full` (default)	Sidebars sit at the viewport edges; guide articles keep a readable centered column
`centered`	Nav + main + TOC share a centered max-width column (~`88rem`); the header bar stays full bleed with inner content aligned to the same column

More theme options (fonts, background, custom CSS) are tracked under Customization.

navbar_links:
  - text: GitHub
    url: https://github.com/acme/docs
    type: minimal
  - text: App
    url: https://app.pinnate.dev
    type: filled

Key	Aliases	Values
`text`	`label`	Button label
`url`	`href`	Absolute or site-relative URL
`type`	`style`	`minimal` (default), `filled`, `outlined`

Sections

Each sections: item is one of:

Guide

Discovers Markdown under path (relative to the sync root).

- name: Guide
  slug: guide
  path: .
  exclude:
    - README.md

Key	Notes
`name`	Top-nav label
`slug`	URL segment; derived from `name` if omitted
`path`	Directory of Markdown; `.` means sync root
`exclude`	Merged with site-level `exclude`
`pages`	Optional explicit file list (order preserved); otherwise discover all `.md`/`.mdx`

API embed

- name: API
  slug: api
  api: payments   # slug, id, or (for some resources) name

Resolves an API in the same organization. The section renders the interactive OpenAPI reference for the latest published document.

SDK embed

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

CLI embed

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

Label-only parent — no URL of its own:

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

Children can be guides or embeds. See Navigation.

Discovery and excludes

With discovery (no pages: list):

Collect .md / .mdx under the section path
Drop paths matching site or section exclude globs
Sort by frontmatter position, then shallower paths, then path name
Build sidebar folders from directories
Rewrite relative Markdown links to public /{section}/{pageSlug} URLs

If any guide section yields zero pages after excludes, sync fails with a validation error.

Visibility

visibility: public   # or private

Private sites require organization membership to read. See Visibility and Authentication.

Without `sections:`

If site.yaml omits sections:, sync fills the existing guide section from Markdown under the root and preserves embed sections already attached in the console. Prefer declaring sections: for reproducible docs-as-code.

site.yaml reference — field-by-field matrix
Project structure
Navigation
Embeds