Rich Content Blocks Demo

Every block on this page is authored in plain markdown. Each section explains when to use the block, shows the exact syntax, then renders the real thing right below it.

Callouts

Use callouts to pull an aside out of the reading flow — a tip, a warning, a technical detail — without breaking the argument of the article.

:::tip Batch your writes
Directus accepts arrays on create endpoints — one request beats fifty.
:::

Checklist

Use a checklist when the reader should walk away with actions, open questions, and known risks — each state gets its own marker.

:::checklist Launch checklist
[x] Confirm the source system.
[ ] Test the empty state.
! Validate permissions before production.
? What happens if the API fails?
* Document the authoring pattern.
- Keep the fallback simple.
Keep this unmarked item neutral.
:::

Embed

Use an embed to bring a video into the article without pasting raw iframes — YouTube and Vimeo URLs are converted automatically, anything else degrades to a link.

:::embed Airflow in three minutes
https://www.youtube.com/watch?v=AHMm1wfGuHE
:::

An unsupported URL never breaks the article — it renders as an outbound link instead:

:::embed Conference talk
https://example.com/talks/data-modeling
:::

Metric

Use a single metric when one number carries the paragraph. Write symbol: down and the renderer translates the word into the glyph.

:::metric
label: Build time reduced
value: 38%
caption: After removing duplicate transforms.
symbol: down
tone: green
:::

Metrics grid

Use a metrics grid for a compact editorial snapshot — separate cards with ---.

:::metrics Pipeline snapshot
label: Build time
value: 38%
caption: Faster after removing duplicate transforms.
symbol: down
tone: green

---

label: Error rate
value: 2.1%
caption: Measured across the last production run.
symbol: up
tone: red

---

label: Review status
value: Stable
caption: No blocking issues found.
symbol: neutral
tone: yellow

---

label: Quality gate
value: Passed
caption: Build, check, and render tests passed.
symbol: ✓
tone: blue
:::

Formula

Use a formula block when notation matters — the math is rendered server-side with KaTeX, not typed out as plain text.

:::formula Mass-energy equivalence
E = mc^2
:::

Fields let you attach a caption, and value: keeps multi-part formulas on one line:

:::formula Renewal rate
value: \text{Renewal Rate} = \frac{\text{Renewed Accounts}}{\text{Eligible Accounts}} \times 100
caption: Keep the denominator consistent across reporting periods.
:::

Plain fractions work too:

Math also works inline — Einstein's $E = mc^2$ sits inside a sentence — and as a standalone block:

$$
\text{Throughput} = \frac{\text{Rows processed}}{\text{Wall-clock seconds}}
$$

Detail and details

Use a details block to fold depth away from the main read — implementation notes, raw logs, edge cases. One nested level is supported, including text panels and callouts.

:::details Implementation notes
This paragraph renders inside the expanded area.

:::text Example
A simple nested text panel inside the details block.
:::

:::warning Production caution
Check permissions before using this pattern in production.
:::
:::

The singular form behaves identically:

:::detail Why this matters
Readers who want the short version never have to scroll past the long one.
:::

Image grid

Use an image grid for screenshots and figures — one image renders full width, two to four flow into a grid, and every image opens in the lightbox. A markdown image title becomes the lightbox caption.

:::imagegrid Case-study covers
![Airflow retry framework cover](https://api.data-dreamer.net/assets/5230cdb2-8204-46c0-a179-0ac1662d2f51 "Retry framework, cover art")
![Maria Khan avatar](https://api.data-dreamer.net/assets/200ef190-a1ae-4cc7-9181-1be16d4ca12c "Maria Khan")
:::

One image:

Two images:

Three images:

Four images, with a grid title:

Divider

Use a divider to mark an editorial beat between phases of an article — quieter than a heading, stronger than a paragraph break.

:::divider
:::

:::divider Next phase
:::

:::divider
***
:::

:::divider
-x-
:::

:::divider
label: Phase two
pattern: -x-
tone: accent
:::

Everyday markdown

All the ordinary markdown keeps working alongside the blocks. Bold, italic, inline code, and links render as always.

Lists

• Unordered item one
• Unordered item two

1. Ordered item one
2. Ordered item two

Table

Code fence

def renewal_rate(renewed: int, eligible: int) -> float:
    return renewed / eligible * 100

Standalone image

Horizontal rule

Quotes

Use > for a quote and >> for a nested subpoint — the nested part keeps a connected vertical rule instead of floating away.

Main quoted idea

Nested subpoint Another nested subpoint Return to main quote

Line-separated nesting also holds together:

Nested subpoint that should visually continue as a subpoint.

That's the full set. Every block above is additive to the existing pipeline — old posts render exactly as before.