Header

The header is configured in settings/header.md. It controls your brand display, navigation links, and utility buttons.

Brand display

The brandDisplay setting controls how your site name and logo appear in the header:

The brand name defaults to brandName in settings/meta.md. Override it for the header with the brandName field.

The brand always links to /.

Adding a custom logo

To use your own logo, place the image file in your media/ folder (e.g. media/logo.svg) and set brandImage in settings/meta.md:

# settings/meta.md
brandImage: /media/logo.svg

Then set your display mode in settings/header.md:

# settings/header.md
brandDisplay: image-text

SVG is recommended for crisp rendering at any size. PNG and JPG also work. The default is /theme/images/logo.svg — a placeholder you can replace or override.

Brand images support image modifiers — append +circle, +bw, +height:N, and other modifiers directly to the brandImage value.

If you only want the logo with no text, use brandDisplay: image. For a logo alongside your site name, use image-text or text-image.

See Brand Display for full details on display modes, image modifiers, footer brand, and content variables.

Navigation items

Add links to the items: list. Each item is a label followed by a slug:

items:
  - Home: /
  - Features: /features
  - Pricing: /pricing
  - Docs: /docs

Labels without slugs are auto-scaffolded — sitemd generates the slug and creates a placeholder page on the next build. See Navigation for details.

Dropdown groups

Use a trailing colon or the group: prefix to create dropdown menus:

items:
  - Product:
    - Features: /features
    - Pricing: /pricing
    - Changelog: /changelog
  - group: docs

Inline children appear in a dropdown on hover. The group: prefix pulls children from settings/groups.md automatically. See Groups for the full group system.

Buttons

Prefix an item with button: to render it as a styled button:

items:
  - Home: /
  - button: Get Started: /docs/getting-started
  - button: Learn More: /features +outline

Add +outline for a secondary style or +color:#hex for a custom color. See Buttons & Links for all options.

External links

Links to external URLs open in a new tab automatically:

items:
  - GitHub: https://github.com/your-org/your-repo

Override window behavior with +newtab or +sametab:

items:
  - Preview: /demo +newtab
  - GitHub: https://github.com/org/repo +sametab

Search

The header includes a search button by default. Toggle it with the search setting:

search: show

Even when hidden, site-wide search is always available via ⌘K (Mac) or Ctrl+K (Windows/Linux).

Theme mode toggle

Show or hide the light/dark/paper mode toggle:

themeModeToggle: show

Set to hide to remove the toggle while keeping theme support active. See Themes for how modes work.

Auth button

When an auth provider is configured, the header shows an account button. Control its visibility:

headerAuth: show

Set to hide to remove the button. The auth system continues to work — users just won't see the header shortcut.

Full reference

# settings/header.md
---
# Override brand name (defaults to brandName in meta.md)
# brandName:

# Brand display: text, image-text, text-image, or image
# Logo path is set via brandImage in settings/meta.md
brandDisplay: text

# Theme mode toggle: show or hide
themeModeToggle: show

# Search button: show or hide (⌘K / Ctrl+K always works)
search: show

# Account button: show or hide (requires auth provider)
headerAuth: show

# Navigation items
items:
  - Home: /
  - Features: /features
  - Pricing: /pricing
  - Docs: /docs
---