# Tooltips & Modals

Tooltips add contextual help inline. Modals display rich content in an overlay without leaving the page — triggered by any link.

## Tooltips

Wrap text in `[brackets]` followed by `{curly braces}` to create a tooltip:

```markdown
Pricing is based on [active users]{Users who logged in at least once in the billing period} per month.
```

Pricing is based on [active users]{Users who logged in at least once in the billing period} per month.

Tooltips appear on hover (desktop) or tap (mobile). They work anywhere inline text works — paragraphs, lists, table cells, headings.

### More examples

- The API uses [JWT tokens]{JSON Web Tokens — signed, stateless authentication tokens} for auth
- Plans renew on the [billing date]{The date you first subscribed, adjusted for month length}
- Status: [Active]{This account is in good standing and fully operational}

## Modals

Define a modal block with `modal: id` followed by indented content:

```markdown
modal: team-info
  ## Meet the Team

  We're a small group of developers and designers building tools we love to use.

  - **Sara** — Engineering lead
  - **James** — Product design
  - **Priya** — Developer experience

  button: Say Hello: /contact
```

Trigger the modal from any link using `#modal:id`:

```markdown
[Meet our team](#modal:team-info)
```

modal: team-info
  ## Meet the Team

  We're a small group of developers and designers building tools we love to use.

  - **Sara** — Engineering lead
  - **James** — Product design
  - **Priya** — Developer experience

  button: Say Hello: /contact

Try it: [Meet our team](#modal:team-info)

Modals support the full range of sitemd content — buttons, cards, forms, images, embeds, and any other component that works on a regular page.

## Tabbed Modals

Add `tab: Label` lines to organize modal content into tabs:

```markdown
modal: shipping
  tab: Domestic
    ## Domestic Shipping

    **Free** on orders over $50.

    - Standard: 5–7 business days
    - Express: 2–3 business days

    button: View Cart: /cart
  tab: International
    ## International Shipping

    **$15 flat rate** worldwide.

    - Standard: 10–14 business days
    - Express: 5–7 business days
    - Tracking included

    button: View Cart: /cart
```

modal: shipping
  tab: Domestic
    **Free** on orders over $50. Standard delivery in 5–7 business days, express in 2–3.

    button: View Cart: none
  tab: International
    **$15 flat rate** worldwide. Standard in 10–14 business days, express in 5–7. Tracking included.

    button: View Cart: none

[View shipping options](#modal:shipping)

Tabs scroll horizontally on mobile if there are many. The first tab is shown by default.

## Global Modals

Inline `modal:` blocks are scoped to the page they're defined on. To share a modal across your entire site, create a file in the `modals/` directory:

```
sitemd/
  modals/
    contact-form.md
    terms.md
  pages/
    ...
```

The filename becomes the modal ID. A file at `modals/terms.md` creates a modal with ID `terms`, triggered by `[link](#modal:terms)` on any page.

The file content uses the same format as inline modal content — raw markdown for a single panel, or `tab:` lines for tabs:

```markdown
## Terms of Service

Last updated: March 2026

By using this service, you agree to...

button: I Agree: /signup
```

Tabbed global modal:

```markdown
tab: Terms
  ## Terms of Service

  By using this service, you agree to...

tab: Privacy
  ## Privacy Policy

  We collect only the data necessary to...
```

Global modals support the full range of sitemd components — buttons, cards, forms, images, and embeds.

## Closing Modals

Modals close when the visitor:

- Clicks the **X** button
- Clicks the backdrop (area outside the modal)
- Presses **Escape**

Page scrolling is locked while a modal is open and restored when it closes.

## Syntax Reference

### Tooltip

```markdown
[visible text]{tooltip content}
```

| Part | Description |
|---|---|
| `[visible text]` | The text shown inline, with a dotted underline |
| `{tooltip content}` | Plain text shown on hover/focus |

### Modal

```markdown
modal: unique-id
  Content here (indented 2+ spaces)...
```

| Part | Description |
|---|---|
| `modal: id` | Inline modal — declares a modal with a unique ID (letters, numbers, hyphens) |
| Indented content | Any sitemd markdown — processed like regular page content |
| `tab: Label` | Starts a new tab section (optional, requires 2+ tabs) |
| `modals/name.md` | Global modal — file in `modals/` directory, available on every page |

### Modal trigger

```markdown
[link text](#modal:unique-id)
```

Use `#modal:` followed by the modal's ID as the link target. Works on regular links and button links:

```markdown
button: View Details: #modal:details
```

button: Shipping Info: #modal:shipping