vitrine

docs: document the :::type callout syntax in the README

commit 40c7f54f5b289c7e1d8abce2ff167cf53672a46a · parent 5c3673b783 · browse this tree
Ximianth, 2026-08-09 10:48:03 UTC

Adds a Callouts section beside Theming describing the colon-fence
syntax, the emitted class shape, the styled type vocabulary, and the
no-nesting / runs-to-end behavior.

diff --git a/README.md b/README.md
index 2a86879..f5c1a9c 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,34 @@ on every build and every host.
 The `-theme-seed` flag substitutes any string for the hostname segment --
 useful for testing, or if you dislike the color your hostname landed on.
 
+Callouts
+--------
+
+Markdown can carry callout boxes (notes, warnings, tips, and the like)
+using colon fences:
+
+```
+:::warning  Optional title text
+body content, which is **full markdown**
+:::
+```
+
+- A line of three-or-more colons followed by a non-empty remainder opens a callout.
+  The first word of the remainder is the callout *type*; anything after it is an optional *title*.
+- A line of three-or-more colons alone closes it.
+- The body is ordinary markdown: lists, emphasis, links, and code all work inside.
+
+The rendered box is `<div class="callout callout-{type}">`
+(matching the markdown-it-container / VuePress convention,
+so docs authored for those tools render as intended).
+The types `note`, `info`, `tip`, `important`, `warning`, `caution`, and `danger`
+get distinct accent colors; note and info ride the per-host accent.
+An unknown type still renders as a plain neutral box.
+
+Callouts do not nest, by design,
+and an unterminated callout simply runs to the end of the document rather than breaking it.
+
+
 expose-git
 ----------