:::contentbit

The generic pack

Eight blocks, one registry

Everything below (descriptions, guidance, examples) comes from the same registry that validates content and writes the LLM authoring instructions. The rendered panes are live: the styled pack rendering each block's real example.

machine-readable version: generated block reference

:::callout

Highlighted note, tip, warning, important, or TLDR box.

Use when

  • Practical advice that prevents a common mistake (tip)
  • Context the reader must not miss (note/important)
  • Something that ruins the result if ignored (warning)
  • A 1-3 sentence summary at the top of a section (tldr)

Avoid when

  • Regular prose that is not a standout remark
  • More than one callout in the same section
  • Content longer than ~3 sentences
example.md
:::callout{type="tip" title="Worth knowing"}Always weigh flour — volume measures drift by 20%.:::
rendered

:::steps

Ordered process steps with visual numbering.

Use when

  • Sequential processes where order matters
  • 3+ steps that benefit from numbering

Avoid when

  • Unordered tips — use a bullet list
  • A single step — write it in prose
example.md
:::steps1. Combine flour and water2. Rest 20 minutes3. Add salt and mix:::
rendered
  1. 1

    Combine flour and water

  2. 2

    Rest 20 minutes

  3. 3

    Add salt and mix

:::key-metrics

Scannable stat cards: a large value with a short label.

Use when

  • Surfacing 2-8 numbers the reader should remember
  • Replacing a stats paragraph

Avoid when

  • Values without a clear unit or context
  • Long textual descriptions
example.md
:::key-metrics- 42% | Conversion lift- 18ms | Median parse time:::
rendered
42%
Conversion lift
18ms
Median parse time

:::quick-ref

Compact key/value reference card.

Use when

  • Facts a reader will return to (temperatures, ratios, durations)
  • At-a-glance summaries near the top of a guide

Avoid when

  • Narrative content
  • Comparing options — use comparison instead
example.md
:::quick-ref- Hydration | 65%- Proof time | 2h at 24°C:::
rendered
Hydration
65%
Proof time
2h at 24°C

:::comparison

Side-by-side comparison of exactly two options.

Use when

  • Comparing exactly two things across attributes
  • Replacing a two-column Markdown table

Avoid when

  • Comparing more than two things
  • Only one row of comparison
example.md
:::comparison{left="Option A" right="Option B"}- Speed | Fast | Slow- Setup | Simple | Advanced:::
rendered
Option AOption B
SpeedFastSlow
SetupSimpleAdvanced

:::pros-cons

Paired advantages (+) and disadvantages (-) of one option.

Use when

  • Evaluating a single option's trade-offs
  • Summarizing a review

Avoid when

  • Comparing two options — use comparison
  • Only positives or only negatives
example.md
:::pros-cons+ Cheap to run+ Fast setup- No offline mode:::
rendered
Pros

  • Cheap to run

  • Fast setup

Cons

  • No offline mode

:::tabs

interactive

Tabbed switcher for alternative methods or variants — the reader picks one.

Use when

  • Two or more alternative methods for the same task
  • Variants by equipment, audience, or budget

Avoid when

  • Side-by-side comparison — use comparison
  • Sequential content — use steps
example.md
:::tabs::tab{title="Fast"}Use this when time matters.::tab{title="Cheap"}Use this when budget matters.:::
rendered

Use this when time matters.

:::faq

interactive

Frequently asked questions with expandable answers.

Use when

  • Real questions readers ask about the topic
  • End-of-article FAQ sections

Avoid when

  • Content that is not literally question/answer
  • A single trivial question
example.md
:::faq::faq-item{question="Can I freeze it?"}Yes, up to 3 months.:::
rendered