# Buttons & Links

Buttons work everywhere — header nav, footer, sidebar, and markdown content. They use the same link syntax as everything else in sitemd.

## Examples

### Small (Default)

button: Filled: none
button: Outline: none +outline
button: Custom Color: none +color:red
button: Outline Custom: none +outline +color:red

### Big

button: Filled: none +big
button: Outline: none +outline +big
button: Custom Color: none +color:red +big

### No-link buttons

button: Pointer (none): none
button: No pointer (silent): silent
button: None Outline: none +outline
button: Silent Outline: silent +outline

## Buttons in settings files

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

```yaml
# settings/header.md
items:
  - Home: /
  - Features: /features
  - button: Get Started: /docs/getting-started
```

This works in `settings/header.md`, `settings/footer.md`, and `settings/groups.md`:

```yaml
# settings/footer.md
groups:
  - heading: Get Started
    links:
      - Documentation: /docs
      - button: Sign Up: https://app.example.com
```

## Buttons in markdown

Use `button:` on its own line inside any page:

```markdown
button: Get Started: /docs/getting-started
button: View Demo: /demo +outline
```

The syntax is identical to settings files — same label, slug, and modifier format.

## Button rows

Consecutive `button:` lines (no blank line between them) render side by side as a row:

```markdown
button: Get Started: /signup
button: Learn More: /docs +outline
```

A blank line between buttons creates separate rows.

Button rows are left-aligned by default. Use [alignment fences](/docs/content-alignment) to center or right-align them.

## Button sizes

Content buttons come in two sizes. The default is compact. Add `+big` for a larger button:

```markdown
button: Default Button: /signup
button: Big Button: /signup +big
```

All buttons in a row should use the same size — if any button has `+big`, the whole row uses the big size.

## Button variants

The default button is filled with your theme's accent color. Add `+outline` for a secondary style:

```yaml
- button: Primary Action: /signup
- button: Secondary Action: /docs +outline
```

| Variant | Look |
|---|---|
| filled (default) | Accent background, white text |
| `+outline` | Transparent background, accent border and text |

## Custom button color

Override the accent color on any button with `+color:name` or `+color:#hex`:

```yaml
- button: Buy Now: /pricing +color:rose
- button: Learn More: /docs +outline +color:emerald
- button: Custom Hex: /about +color:#7c3aed
```

Use any name from the [color palette](/docs/colors) or a raw hex value (3 or 6 digits). Modifiers are composable — combine `+outline`, `+color`, `+newtab` in any order.

button: Red: silent +color:red
button: Orange: silent +color:orange
button: Amber: silent +color:amber
button: Yellow: silent +color:yellow
button: Lime: silent +color:lime
button: Green: silent +color:green
button: Emerald: silent +color:emerald
button: Teal: silent +color:teal
button: Cyan: silent +color:cyan
button: Sky: silent +color:sky
button: Blue: silent +color:blue
button: Indigo: silent +color:indigo
button: Violet: silent +color:violet
button: Purple: silent +color:purple
button: Fuchsia: silent +color:fuchsia
button: Pink: silent +color:pink
button: Rose: silent +color:rose
button: Slate: silent +color:slate
button: Gray: silent +color:gray
button: Zinc: silent +color:zinc
button: Stone: silent +color:stone

## Button icons

Add an icon to any button with `+icon:name`. Icons come from the [Lucide](https://lucide.dev/icons/) library (1900+ icons). By default, the icon appears to the left of the label. Use `+icon-right:name` to place it on the right. See [Icons](/docs/icons) for the full icon system documentation.

```markdown
button: Get Started: /signup +icon:rocket
button: Learn More: /docs +icon-right:arrow-right +outline
```

button: Get Started: none +icon:rocket
button: Learn More: none +icon-right:arrow-right +outline

Icons work with all other modifiers — combine with `+outline`, `+color`, `+big`:

button: Settings: none +icon:settings +outline +color:violet
button: Download: none +icon:download +big
button: Home: none +icon:home +color:emerald

The three icon modifiers:

| Modifier | Position |
|---|---|
| `+icon:name` | Left of label (default) |
| `+icon-left:name` | Left of label (explicit) |
| `+icon-right:name` | Right of label |

Icons inherit the button's text color automatically — white on filled buttons, accent on outline buttons.

## Non-link buttons

Use `none` or `silent` as the target to render a button that doesn't navigate anywhere:

```markdown
button: Label: none
button: Label: silent
```

| Target | Behavior |
|---|---|
| `none` | Shows pointer cursor on hover, but clicking does nothing |
| `silent` | Default cursor, no interaction — purely visual |

Both render as a `<span>` instead of an `<a>`. Useful for placeholder buttons, labels, or disabled states. All other modifiers (`+outline`, `+color`, `+big`) work normally.

## Anchor links

Every heading on your site automatically gets an ID based on its text. A heading like `## Getting Started` gets the ID `getting-started`.

Link to any heading on the current page with a hash:

```markdown
[Jump to setup](#getting-started)
```

Link to a heading on another page:

```markdown
[See the theme docs](/docs/themes#custom-colors)
```

Cross-page anchor links work with sitemd's instant navigation — the target page loads and scrolls to the heading automatically.

### Try it

These links jump to sections on this page:

- [Jump to Examples](#examples)
- [Jump to Button Rows](#button-rows)
- [Jump to Inline Anchors](#inline-anchors)
- [Jump to Full Modifier Reference](#full-modifier-reference)

These links jump to sections on other pages:

- [Getting Started → Install the Plugin](/docs/getting-started#install-the-plugin)
- [Themes → Light Mode](/docs/themes#light-mode)
- [Navigation → Dropdown Groups](/docs/navigation#dropdown-groups)

### Anchor links in settings files

The same syntax works in header, footer, and group items:

```yaml
items:
  - Pricing Plans: /pricing#plans
  - FAQ: #faq
```

A bare `#id` links to an anchor on the current page. A `/slug#id` links to a specific section on another page.

## Inline anchors

Headings get IDs automatically, but you can also place anchors anywhere with `{#id}` on its own line:

```markdown
Some introductory text.

{#pricing-table}
| Plan | Price |
| ---- | ----- |
| Free | $0/mo |
| Pro  | $20/mo |
```

Now `[See pricing](#pricing-table)` or `[Plans](/pricing#pricing-table)` will scroll directly to the table.

The ID must be lowercase with only letters, numbers, and hyphens.

## Modal triggers

Any link can open a modal overlay by using `#modal:id` as the target:

```markdown
[View details](#modal:details)
button: View Details: #modal:details
```

The modal must be defined on the same page using the `modal:` block syntax. See [Tooltips & Modals](/docs/tooltips-modals) for full details.

## Full modifier reference

All modifiers work on both regular links and buttons. Combine them in any order.

| Modifier | Effect |
|---|---|
| `+newtab` | Open in a new tab |
| `+sametab` | Open in the same tab (overrides default for external links) |
| `+outline` | Outline button variant (only on `button:` items) |
| `+big` | Larger button size (only in markdown content) |
| `+color:#hex` | Custom button color (only on `button:` items) |
| `+icon:name` | Icon left of label (only on `button:` items) |
| `+icon-left:name` | Icon left of label, explicit (only on `button:` items) |
| `+icon-right:name` | Icon right of label (only on `button:` items) |