Callouts

Docspire supports configurable callouts out of the box. By default, it supports the following callouts:

::: callout
This is a `callout` callout.
:::

::: details
This is a `details` callout.
:::

::: note
This is a `note` callout.
:::

::: tip
This is a `tip` callout.
:::

::: warning
This is a `warning` callout.
:::

::: caution
This is a `caution` callout.
:::

::: important
This is a `important` callout.
:::

::: danger
This is a `danger` callout.
:::

::: info
This is a `info` callout.
:::

You can nest callouts:

::::: note Parent

Parent content

:::: caution Child { .test }

Child content

::: warning Grandchild { test }
Grandchild content
:::

Child content

::::

Parent content

:::::

You can optionally specify a title, which will override the default title. You can even use Markdown in it!

::: warning Here be **dragons**
This is a note callout with a custom title.
:::

Callouts can be collapsible, and start off as expanded or collapsed:

::: tip.collapsed If you have a floob
Here’s how to turn it into a flab
:::

::: tip.collapsible If you have a floob
Here’s how to turn it into a flab
:::

You can add modifiers via CSS classes:

::: note { .no-title }
This is a note without a title.
:::

::: note { .no-icon }
This is a note without an icon.
:::

::: note { .no-title .no-icon }
This is a note without a title or an icon.
:::

Customization

Docspire comes with a number of callouts out of the box, but you can add your own. These are the default options:

{
  default: {
    color: 'gray'
  },
  types: {
    callout: {
      icon: false,
      title: false
    },
    details: {
      collapsed: true
    },
    note: {
      color: 'green',
      icon: 'info',
      title: 'Note'
    },
    tip: {
      color: 'green',
      icon: 'tip'
    },
    warning: {
      color: 'yellow',
      icon: 'warning',
      role: 'alert'
    },
    caution: {
      color: 'red',
      icon: 'caution',
      role: 'alert'
    },
    important: {
      color: 'indigo',
      icon: 'important'
    },
    danger: {
      extends: 'caution'
    },
    info: {
      extends: 'note',
      color: 'blue',
      title: false
    }
  }
}

default specifies default options for all callouts, whereas types specifies what types are available and what their options are.

This is what each option means:

• extends allows you to create aliases of other callout types, with or without overriding some of their options.
• title: The default title, or false for none (if not false, a title is auto-generated from the type). If a title is provided in the callout, this is ignored.
• icon: The default icon, or false for none (mainly useful as an override)
• color: The default color or neutral for none (mainly useful as an override)
• collapsed and collapsible allow you to apply these modifiers by default.

Roadmap

Things we want to add to callouts at some point:

• dismissible or closable flag to make callouts dismissable (and store it in local storage)
• GitHub-style callout syntax
• Predefined appearances
• A way to style callouts as a full-width banner (either flag or heuristic)