# Callout

Highlight information readers should not miss.

import { Callout } from '@prosefly/astro-components';

Use `Callout` when a reader needs to notice something before continuing:
requirements, safe defaults, limits, destructive actions, or shortcuts. Keep
callouts short enough to scan without breaking the page flow.

Callouts are also known as admonitions in many documentation systems. This
package uses `Callout` for the component and API names.

## Import

```mdx
import { Callout } from '@prosefly/astro-components';
```

## Write A Useful Callout

<Callout type="note" title="Document the default behavior">
  Notes are a safe default for implementation details, caveats, and extra
  context.
</Callout>

```mdx
<Callout type="note" title="Document the default behavior">
  Notes are a safe default for implementation details, caveats, and extra
  context.
</Callout>
```

## Choose The Right Type

<Callout type="note" title="Note">
  Use `note` for neutral context, defaults, and implementation details.
</Callout>

<Callout type="tip" title="Tip">
  Use `tip` for recommended workflows, shortcuts, and better ways to complete
  the same task.
</Callout>

<Callout type="warning" title="Warning">
  Use `warning` when a choice can cause broken output, confusing behavior, or
  extra setup work.
</Callout>

<Callout type="danger" title="Danger">
  Use `danger` for destructive commands, security-sensitive steps, and
  irreversible changes.
</Callout>

```mdx
<Callout type="note" title="Note">
  Use `note` for neutral context, defaults, and implementation details.
</Callout>

<Callout type="tip" title="Tip">
  Use `tip` for recommended workflows, shortcuts, and better ways to complete
  the same task.
</Callout>

<Callout type="warning" title="Warning">
  Use `warning` when a choice can cause broken output, confusing behavior, or
  extra setup work.
</Callout>

<Callout type="danger" title="Danger">
  Use `danger` for destructive commands, security-sensitive steps, and
  irreversible changes.
</Callout>
```

## With Rich Content

<Callout type="tip" title="Put the action first">
  Give the reader the command or decision before the explanation.

  ```sh
  pnpm add @prosefly/astro-components
  ```

  Add caveats only after the action is clear.
</Callout>

````mdx
<Callout type="tip" title="Put the action first">
  Give the reader the command or decision before the explanation.

  ```sh
  pnpm add @prosefly/astro-components
  ```

  Add caveats only after the action is clear.
</Callout>
````

## Markdown Directives

Enable `remarkCalloutDirectives` when authors should write callouts, also known
as admonitions, without importing the component in every MDX file.

```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import {
  remarkCalloutDirectives,
  unified,
} from '@prosefly/astro-components/markdown';

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [remarkCalloutDirectives],
    }),
  },
});
```

:::tip[Directive syntax]
Use `note`, `tip`, `warning`, or `danger`. The `caution` directive is accepted
as a `warning` alias for Starlight compatibility.
:::

```md
:::tip[Directive syntax]
Use `note`, `tip`, `warning`, or `danger`. The `caution` directive is accepted
as a `warning` alias for Starlight compatibility.
:::
```

## Props

| Prop | Type | Default |
| --- | --- | --- |
| `title` | `string` | none |
| `type` | `'note' \| 'tip' \| 'warning' \| 'danger'` | `'note'` |

## CSS Variables

Each callout type maps to the shared semantic palette first: `note` uses
`--pf-info-*`, `tip` uses `--pf-success-*`, `warning` uses `--pf-warning-*`,
and `danger` uses `--pf-danger-*`. Override the type-specific callout tokens
only when callouts need to differ from badges and other components.

| Token | Used For |
| --- | --- |
| `--pf-info`, `--pf-info-ink`, `--pf-info-soft` | Default note palette |
| `--pf-success`, `--pf-success-ink`, `--pf-success-soft` | Default tip palette |
| `--pf-warning`, `--pf-warning-ink`, `--pf-warning-soft` | Default warning palette |
| `--pf-danger`, `--pf-danger-ink`, `--pf-danger-soft` | Default danger palette |
| `--pf-callout-note-{color\|ink\|bg}` | Note-only overrides |
| `--pf-callout-tip-{color\|ink\|bg}` | Tip-only overrides |
| `--pf-callout-warning-{color\|ink\|bg}` | Warning-only overrides |
| `--pf-callout-danger-{color\|ink\|bg}` | Danger-only overrides |