# Navigation

Control your site's header navigation from `settings/header.md`. Add a link, save, and the page is created for you.

## Basic setup

Navigation items live in the `items:` list in `settings/header.md`:

```yaml
# settings/header.md
items:
  - Home: /
  - Features: /features
  - Pricing: /pricing
  - Docs: /docs
```

Each item is a label followed by a slug. The label appears in the header, and the slug is the URL path.

## Auto-scaffold

You don't need to create a page file before adding it to navigation. Just add the label — sitemd generates the slug and creates the page for you.

```yaml
items:
  - Home: /
  - About
  - Contact
```

On the next build:

1. `About` gets the slug `/about`, `Contact` gets `/contact`
2. `pages/about.md` and `pages/contact.md` are created with placeholder content
3. `header.md` is patched with the generated slugs:

```yaml
items:
  - Home: /
  - About: /about
  - Contact: /contact
```

Existing pages are never overwritten. External links (`https://...`) are never scaffolded.

## Dropdown groups

Use a trailing colon to create a group with child links:

```yaml
items:
  - Home: /
  - Product:
    - Features: /features
    - Pricing: /pricing
    - Changelog: /changelog
  - Docs: /docs
```

The group label becomes a dropdown toggle in the header. Children appear in a dropdown menu on hover.

If a matching [group](/docs/groups) exists in `settings/groups.md`, the dropdown children are pulled from it automatically — you don't need to list them inline. Adding or removing a group entry in `header.md` updates the group's locations in `groups.md` on the next build (and vice versa).

```yaml
items:
  - Home: /
  - Product:
  - Docs: /docs
```

Children without slugs are auto-scaffolded under the group folder:

```yaml
items:
  - Product:
    - Features
    - Pricing
    - Changelog
```

This creates `pages/product/features.md`, `pages/product/pricing.md`, and `pages/product/changelog.md` with slugs like `/product/features`. A matching group is also created in `settings/groups.md` with a sidebar for these pages.

## Buttons

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

```yaml
items:
  - Home: /
  - Features: /features
  - button: Sign Up: /pricing
```

Add `+outline` for a secondary style, or `+color:#hex` to override the accent color:

```yaml
  - button: Get Started: /docs/getting-started
  - button: Learn More: /features +outline
  - button: Buy Now: /pricing +color:#e11d48
```

Buttons work in header, footer, sidebar, and markdown content. See [Buttons & Links](/docs/buttons-and-links) for the full reference.

## External links

Links to external URLs open in a new tab automatically:

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

You can override window behavior with `+newtab` and `+sametab` suffixes:

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

See [link targets](/docs/pages-and-content#link-targets) for details.

## Header and footer

For the full settings reference for each, see the standalone doc pages:

- [Header](/docs/header) — brand display, logo, search toggle, theme mode, auth button, and the complete `settings/header.md` reference
- [Footer](/docs/footer) — navigation groups, social icon links, copyright, tagline, mailto links, and the complete `settings/footer.md` reference


## Sidebar

Pages in a group with a `sidebar` location get a two-column layout with section navigation. On mobile, sidebar content moves into the hamburger menu alongside header links. See the [Sidebar](/docs/sidebar) doc for search, anchors, and mobile behavior.