A tour of MDX in this blog

Most of what lands here is written in MDX. The pipeline is small and explicit — remark-gfm for the GitHub-Flavoured Markdown extras, rehype-slug so every heading gets a stable id, rehype-pretty-code for syntax-highlighted fences. This post is a working tour of every primitive that pipeline supports, so I have one place to come back to when I need to remember how something renders.

If you're reading this on the rendered site, every example in the sections below is the actual output. If you're reading the source, what you see is exactly what got shipped to MongoDB and then back out again.

Inline formatting

The basics: bold, italics (the editorial italic font, served from Instrument Serif), strikethrough, and a touch of inline code for tokens like npm run build or Array.prototype.flat. External links like the Next.js docs open in a new tab; internal ones like the projects index go through Next's client router. The link styling sticks to the acid accent so a paragraph never breaks visual rhythm.

Block quotes

The detail comes through as you do the work. Whatever you're stuck on — sit with it longer than feels comfortable, then strip out half of what you've written.

That's the rule of thumb behind the body copy on this site. Block quotes use the editorial italic and a thin acid-green left rule.

Lists

A flat unordered list:

• Feature flags should be cheap to add and cheap to remove
• Zero-config is a marketing claim; sane defaults are a real one
• The compiler is an enthusiastic intern, not a senior engineer

A numbered list:

1. Read the request body
2. Validate with Zod
3. Mutate exactly one collection
4. Revalidate exactly the paths that consume it

A nested list — useful inside engineering posts when one bullet has its own three-step procedure:

• Pre-flight checks
  • Confirm the user has write permission on the resource
  • Confirm the resource is not locked by another session
• The mutation itself, scoped to a single transaction
• Post-mutation cache invalidation

A GitHub task list — the checkboxes use the same acid green as the rest of the accent system:

• Define the schema
• Add the Zod validator
• Wire the admin form
• Build the public-facing component
• Write the seed content that proves it works

Code blocks

Plain code with no language hint renders monospace and dark, no highlighting:

$ pnpm dev
> next dev
- Local: http://localhost:3000

TypeScript, with rehype-pretty-code doing the work. Lines {4-6} are highlighted to draw the eye to the part that matters:

import { z } from "zod";
 
const projectInputSchema = z.object({
  slug: z.string().regex(/^[a-z0-9-]+$/),
  title: z.string().min(1).max(120),
  body: z.string().min(1),
  // …more fields
});

A short JSX block — same highlighter, JSX-aware:

<Callout type="warn" title="Re-validate after every write">
  A mutation that doesn't <code>revalidatePath()</code> the surfaces it
  affects is a mutation users won't see until the next deploy.
</Callout>

Bash with single-line highlighting:

pnpm install
pnpm cms:seed
pnpm dev

JSON, useful when the post is documenting a config:

{
  "name": "portfolio-cms",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "cms:seed": "tsx scripts/seed-cms.ts"
  }
}

Tables

GFM pipe tables get a dedicated horizontally-scrollable wrapper. On narrow screens they scroll without forcing the prose column to widen:

A second table — slightly wider — to show the editorial cell padding and the hover-row treatment:

Images & figures

Markdown's image syntax accepts an optional title in quotes — the third argument. The title is promoted to a real <figcaption> so the image stops pretending the alt text is also the caption:

The same img component handles JSX-style usage too, so <img src="..." alt="..." title="..." /> from inside JSX inside MDX renders identically. That keeps the source readable when the surrounding paragraph already has JSX in it.

Callouts

Five variants, each with its own icon, accent and default title. Pass title="..." to override.

Footnotes

Footnote references¹ use the GFM syntax — [^id] inline, with the body of the note at the bottom. The renderer wraps the footnote section in a <section data-footnotes> block that the prose styles divide off with a hairline rule. Each reference is a back-link too², so the reader can jump down, read the note, and click straight back to the spot they left.

Heading depth

There's no rule against nesting more, but two levels of headings inside the body is usually plenty. Anything deeper and the post is fighting the reader's mental model.

What an h3 looks like

The h3 is slightly smaller than the h2 and breathes a bit less above. It still gets a stable id from rehype-slug, so direct linking to it works.

And an h4 just to prove it

H4 is rare in this blog. When it shows up, it's usually inside a long technical post where a section needs a sub-sub-heading to keep the reading flow.

That's every primitive this blog renders today. If you're building one of your own and want to copy this setup, the configuration is small enough to inline: GFM + slug + pretty-code on the rehype side, a custom img, table, and Callout on the components side. Everything else is just CSS doing the work that the Markdown spec deliberately leaves to the renderer.