Components

A cheat-sheet of every component available when writing posts on this site — the Docusaurus/MDX built-ins and the custom components in src/components/. Each author-facing component is shown rendered live with its source underneath, so you can see what it looks like and copy the exact syntax. Internal theme components (cookie banner, share row, …) are listed at the bottom for completeness.

Keep this page current

A pre-commit hook (scripts/check-components-listed.mjs) fails the commit if a new component under src/components/ isn't mentioned on this page. When you add a component, add it here too.

Admonitions

Callout boxes. Built into Docusaurus — no import. Keywords: note, tip, info, warning, danger. An optional title follows the keyword.

note

A neutral aside.

tip

A handy shortcut.

Going deeper

Extra context for the curious — the recurring pattern on this blog.

warning

Something to watch out for.

danger

A real hazard.

:::tip
A handy shortcut.
:::

:::info[Going deeper]
Extra context for the curious.
:::

Code fences with a title

A fenced code block. Add title="…" for a filename header + copy button. The language after the opening backticks enables syntax highlighting.

example.ts

const greeting: string = "hello";
console.log(greeting);

```ts title="example.ts"
const greeting: string = "hello";
console.log(greeting);
```

Collapsible <details>

Native HTML — a click-to-expand block. Leave a blank line after </summary> so the Markdown inside is parsed.

Click to expand

Hidden content — supports Markdown, lists, and code.

• one
• two

<details>
<summary>Click to expand</summary>

Hidden content — supports **Markdown**, lists, and code.

- one
- two
</details>

Mermaid diagrams

Fenced ```mermaid blocks render as diagrams (enabled site-wide via @docusaurus/theme-mermaid). Rendered diagrams get a click-to-enlarge modal.

⤢ enlarge

```mermaid
flowchart LR
  Author[Author] --> MDX[MDX post]
  MDX --> Page[Rendered page]
```

Highlight <u>

The house convention for marking the single key sentence of a section. Authored <u> renders as a semantic <mark> (highlight), not an underline. Use sparingly.

This is the one sentence a reader should remember.

<u>This is the one sentence a reader should remember.</u>

Tables

Write normal Markdown tables. Every table is automatically wrapped by TableWrapper, which adds horizontal scrolling and edge-fade affordances when the table is wider than the page — no import, nothing to call.

Component	Kind	Import?
ImagePlaceholder	custom	no
Admonition	built-in	no

| Component | Kind | Import? |
| --- | --- | --- |
| ImagePlaceholder | custom | no |
| Admonition | built-in | no |

ImagePlaceholder

Custom, globally registered (no component import — just import the image asset). A lazy-loaded image with a blur-up 🏞️ placeholder until it loads. The main way to add images to a post.

import cover from './images/cover.webp';

<ImagePlaceholder src={cover} alt="A short description of the image" />

Youtube

Custom, globally registered. A responsive, lazy-loaded YouTube embed. Pass the embed URL (/embed/<id>), ideally the youtube-nocookie.com variant.

<Youtube src="https://www.youtube-nocookie.com/embed/VIDEO_ID" />

Button

Custom — a styled link. Requires an explicit import (it's not globally registered).

Read the blog

import Button from "@site/src/components/Button";

<Button to="/blog" variant="primary">Read the blog</Button>

PodcastPlayer

Custom, globally registered. A branded 🎧 audio card for the spoken version of a post. Import the audio asset and pass it as src. (Shown as source only here — a live demo would need an audio file.)

import podcast from './audio/podcast.mp3';

<PodcastPlayer src={podcast} title="Listen to the podcast version" />

Internal components

Not authored inside posts — they're wired into the theme. Listed here so the catalogue is complete (and so the enforcement hook passes).

Component	Purpose	Where it's rendered
TableWrapper	Horizontal-scroll wrapper for wide tables	Automatic, via MDXComponents table: override
Comments	Comments block (currently a no-op stub)	<Comments />, available but inactive
SharePost	Share row (X, LinkedIn, copy link)	Blog post header/footer, via theme/BlogPostItem
ConsentBanner	Cookie-consent opt-in banner	Injected site-wide via theme/Root.js
ManageConsent	Withdraw/revisit consent control	The /privacy page
DiagramModal	Click-to-enlarge modal for mermaid diagrams	Internally by theme/Mermaid

Available but unused

Docusaurus also ships Tabs / TabItem (tabbed content). They work if imported from @theme/Tabs and @theme/TabItem, but no post currently uses them.