# 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:

| Value | What it shows |
|---|---|
| `text` | Site name only (default) |
| `image-text` | Logo left, site name right |
| `text-image` | Site name left, logo right |
| `image` | Logo only |

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`:

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

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

```yaml
# 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](/docs/brand-display#image-modifiers-on-brand-images) — 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](/docs/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:

```yaml
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](/docs/navigation#auto-scaffold) for details.

## Dropdown groups

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

```yaml
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](/docs/groups) for the full group system.

## Buttons

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

```yaml
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](/docs/buttons-and-links) for all options.

## External links

Links to external URLs open in a new tab automatically:

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

Override window behavior with `+newtab` or `+sametab`:

```yaml
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:

```yaml
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:

```yaml
themeModeToggle: show
```

Set to `hide` to remove the toggle while keeping theme support active. See [Themes](/docs/themes) for how modes work.

## Auth button

When an [auth provider](/docs/user-auth) is configured, the header shows an account button. Control its visibility:

```yaml
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

```yaml
# 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
---
```