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)

Big

No-link buttons

Buttons in settings files

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

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

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

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:

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 to center or right-align them.

Button sizes

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

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:

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

Custom button color

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

- 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 or a raw hex value (3 or 6 digits). Modifiers are composable — combine +outline, +color, +newtab in any order.

Button icons

Add an icon to any button with +icon:name. Icons come from the Lucide 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 for the full icon system documentation.

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

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

The three icon modifiers:

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:

button: Label: none
button: Label: silent

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:

[Jump to setup](#getting-started)

Link to a heading on another page:

[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
• Jump to Button Rows
• Jump to Inline Anchors
• Jump to Full Modifier Reference

These links jump to sections on other pages:

• Getting Started → Install the Plugin
• Themes → Light Mode
• Navigation → Dropdown Groups

Anchor links in settings files

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

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:

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:

[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 for full details.

Full modifier reference

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