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:

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 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 for auth
Plans renew on the billing date
Status: Active

Modals

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

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:

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

Try it: Meet our team

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:

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

View shipping options

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:

## Terms of Service

Last updated: March 2026

By using this service, you agree to...

button: I Agree: /signup

Tabbed global modal:

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

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

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

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

button: View Details: #modal:details

Shipping Info