clean-jsdoc-theme

Callouts

Where this works — prose & API docs. Author callouts in any prose (README, tutorials, the docs directory), and the theme also emits one automatically from a @deprecated doc-comment tag in your source.

Callouts are typed, colored notice boxes — the kind you use for a tip, a warning, or an important aside. You write them as GitHub-style alert blockquotes: an ordinary blockquote whose first line is a [!TYPE] marker.

This works in any prose the theme renders — your README, tutorials, and the docs directory — because the promotion happens during the shared HTML normalization pass in from-html.ts.

Syntax

CODE
> [!NOTE]
> Useful information that users should know, even when skimming.

renders as:

Useful information that users should know, even when skimming.

The marker must be the very first thing inside the blockquote (blockquoteToCallout reads it off the first text node and matches ^\s*\[!(\w+)\]\s*). The marker is stripped from the body; everything after it becomes the callout content. An absent or unrecognized marker leaves the blockquote as a plain quote.

The four variants and their markers

There are exactly four callout variants — info, tip, warning, and error. Several GitHub-style keywords fold onto each. This is the complete CALLOUT_ALERTS map from from-html.ts; the marker is case-insensitive (it is lower-cased before lookup):

Marker you writeVariant
[!INFO]info
[!NOTE]info
[!IMPORTANT]info
[!TIP]tip
[!SUCCESS]tip
[!WARNING]warning
[!CAUTION]warning
[!ERROR]error
[!DANGER]error

So [!NOTE] and [!IMPORTANT] both render as the blue info box, [!TIP] and [!SUCCESS] as the green tip box, [!WARNING] and [!CAUTION] as warning, and [!ERROR] and [!DANGER] as error. There is no separate "caution" or "danger" color — they alias onto warning and error.

Every variant, rendered

Info — [!INFO], [!NOTE], [!IMPORTANT]

CODE
> [!IMPORTANT]
> `[!INFO]`, `[!NOTE]`, and `[!IMPORTANT]` all produce this same info box.

[!INFO], [!NOTE], and [!IMPORTANT] all produce this same info box.

Tip — [!TIP], [!SUCCESS]

CODE
> [!TIP]
> `[!TIP]` and `[!SUCCESS]` both fold onto the green tip variant.

[!TIP] and [!SUCCESS] both fold onto the green tip variant.

Warning — [!WARNING], [!CAUTION]

CODE
> [!WARNING]
> `[!WARNING]` and `[!CAUTION]` both render this amber warning box.

[!WARNING] and [!CAUTION] both render this amber warning box.

Error — [!ERROR], [!DANGER]

CODE
> [!DANGER]
> `[!ERROR]` and `[!DANGER]` both render this red error box.

[!ERROR] and [!DANGER] both render this red error box.

Rich content and nesting

The body is normal Markdown — paragraphs, lists, code, links — and callouts promote at any depth, including inside list items, mirroring how GitHub renders alerts nested in lists (promoteCallouts recurses through children):

CODE
> [!TIP]
> You can put **anything** in a callout:
>
> - a list item
> - a `code` span
>
> ```js
> const fenced = "code blocks too";
> ```

You can put anything in a callout:

  • a list item
  • a code span
CODE
const fenced = "code blocks too";

Callouts from doc-comment tags

Callouts are not only a prose feature. When you document a symbol with @deprecated, the theme emits a callout automatically — no marker needed. See deprecationBlock in doclet.ts:

CODE
/**
 * @deprecated Use `@link newApi` instead.
 */

A bare @deprecated with no reason falls back to a kind-aware default sentence ("This method is deprecated and should not be used."), so the box is never blank.

You can also write the alert markers themselves straight into a description — they're promoted exactly as in prose:

CODE
/**
 * Cache statistics.
 *
 * > [!INFO]
 * > Counts reset when you call `clear()`.
 *
 * > [!WARNING]
 * > `get()` mutates recency — avoid it in hot loops.
 */

See an [!INFO] callout authored in a real @module comment on the sample-api module page of the live demo — source in docs-site/src/index.js.

Under the hood

A callout is emitted as a capitalized <Callout type="…"> MDX JSX node (the callout builder in builders.ts). rang registers Callout → MdxBlockquote in mdx-components.tsx, so a callout and a plain markdown blockquote share one component — it just branches to typed styling when type is set. The capitalized name is what lets the variant survive serialization to dwar (a plain > quote can't carry it).

See also