Add callouts

Use callouts when a note, recommendation, requirement, or risk needs to stand apart from the normal task flow.

Add a callout

Start a callout with ::: and its type, then close it with another ::: line:

markdown

::: note
Use `toc.md` when navigation order matters.
:::

Callout bodies support normal Markdown, including multiple paragraphs, lists, links, and code blocks.

Choose a callout type

DocInsight provides five callout types:

Type	Use for
`note`	Helpful context that is worth noticing
`tip`	Optional advice or a faster path
`important`	Information readers must know before continuing
`warning`	A risk that may cause incorrect results, broken output, or other recoverable problems
`danger`	A risk of data loss, security exposure, or another serious consequence that may be difficult to reverse

The following examples show the default title and visual treatment for every type.

Note

Use a note for supporting context that helps readers understand the current task.

Note

Use toc.md when navigation order matters.

Tip

Use a tip for optional advice, a shortcut, or a more efficient approach.

Tip

Run docinsight check before building to find authoring problems without writing output.

Important

Use an important callout for information readers must know before continuing.

Important

Content entries must be included in the same output target before they can cross-reference each other.

Warning

Use a warning when an action may cause incorrect results, broken output, or another problem that requires corrective action.

Warning

Changing mount changes generated output paths and may break existing links.

Danger

Use a danger callout when an action may cause data loss, expose private information, or have another serious consequence that is difficult to reverse.

Danger

Do not publish an asset set that contains credentials or other private files.

Set a custom title

Use the title attribute when the default title does not describe the message:

markdown

::: important title="Before you publish"
Run `docinsight check` and review the selected output target.
:::

Use GitHub-style alerts

DocInsight also recognizes GitHub-style alerts in existing Markdown:

markdown

> [!NOTE]
> Use `toc.md` when navigation order matters.

NOTE, TIP, IMPORTANT, and WARNING map to the matching callout types. CAUTION maps to danger. Prefer the native ::: syntax when authoring new content because it supports callout attributes and nested Markdown directly.