Admonition

An admonition sets a passage apart and says how to read it: a piece of advice, a caution, a danger. Six kinds ship with the tool, and a project declares its own rather than waiting for that list to grow.

The six kinds

<Admonition type="tip">A shortcut, a habit worth taking.</Admonition>

Without a type, the block is a note.

A title of its own

<Admonition type="attention" title="Read this before upgrading">
  …
</Admonition>

Kinds of your own

A kind is a label and a tone. The tone carries the colour, taken from the theme, so a new kind needs no stylesheet and follows whichever theme is active:

// docpensieve.config.mjs
admonitions: {
  review: { label: 'To review', tone: 'attention' },
  legal: { label: 'Legal notice', tone: 'info' },
},

<Admonition type="review">This section awaits a second pair of eyes.</Admonition>

A mark of its own

A kind may carry an icon instead of the drawing of its tone — the logo of a tool, the mark of a team. It names an SVG of the version folder, or an icon of a set, and either is inlined at the build:

admonitions: {
  review: { label: 'To review', tone: 'attention', icon: '/icons/review.svg' },
  shipped: { label: 'Shipped', tone: 'tip', icon: 'simple-icons:github' },
},

A file that does not exist stops the build, naming the path it looked for. An icon set is a package the project installs — see LogoIcon — and a set that is missing stops it too.

The tones are note, info, tip, attention and danger. A kind nobody declared stops the build, listing those that exist: rendered anyway, the block would come out with no colour and no label, and nothing would say why.

Styling

The block takes its colours from the theme's tokens — --dp-tip, --dp-attention, --dp-danger and their -soft grounds — so it follows the light and dark schemes on its own.

A className adds utilities on top:

<Admonition type="tip" className="shadow-sm">
  …
</Admonition>

What it carries

A block holds whatever a page holds — several paragraphs, a list, a code block:

Without JavaScript

Like every component here, it is rendered at the build. It is an aside announced as a note, with its icon hidden from screen readers — the title beside it already says the kind, and saying it twice helps nobody.