Markdown Reference

Every feature the renderer supports, with the markdown that produced it. This page is also the visual test: if something here looks wrong after a change to the generator, the change broke it.

Frontmatter

Every field is optional. A bare .md file with no frontmatter still renders — the title falls back to the first heading, then to the filename.

---
title: Rate Limiter
description: One line used in cards, search results, and social previews.
tags: [redis, token-bucket]          # becomes links to /tags/<tag>/
difficulty: easy | medium | hard     # renders as a badge
status: published                    # or draft → renders as "not written yet"
author: Your Name
created: 2026-07-28
updated: 2026-08-01
---

Admonitions

The GitHub blockquote syntax, extended with custom titles and collapsible variants.

> [!NOTE]
> Body text goes here.

All kinds

Custom titles

Anything after the marker on the same line replaces the default title.

> [!TIP] Prefer distributed ID generation
> It scales horizontally and guarantees uniqueness.

Collapsible

Add - to start collapsed, + to start open. Both render as a native <details>, so they work without JavaScript and are searchable by the browser's find-in-page.

> [!EXAMPLE]- Full capacity calculation
> Hidden until clicked.

> [!ABSTRACT]+ Open by default
> Visible, but the reader can fold it away.

An unrecognised marker is left alone deliberately — > [!WHATEVER] renders as an ordinary blockquote rather than an unstyled mystery box, so a typo is visible instead of silent.

Emoji

Type :name: and get the emoji. Shortcodes inside code spans and fenced blocks are never touched, and an unknown name is left as literal text so typos show up rather than vanishing.

Shortcodes also work in the title and description frontmatter fields, since those never pass through the markdown parser.

Tags

tags: [redis, sharding] in frontmatter does three things: renders chips under the page title, files the page under /tags/redis/ and /tags/sharding/, and feeds the tag filters in search. Tags are matched case-insensitively, so Redis and redis are one tag.

Browse everything at Tags.

Diagrams

Fenced mermaid blocks render client-side and are click-to-zoom. Mermaid only loads on pages that actually contain a diagram.

```mermaid
flowchart LR
  Client --> LB[Load Balancer] --> App[App Servers]
  App --> Cache[(Cache)]
  App --> DB[(Database)]
```

flowchart LR
  Client --> LB[Load Balancer] --> App[App Servers]
  App --> Cache[(Cache)]
  App --> DB[(Database)]

Sequence, class, state, ER, gantt, pie, journey, mindmap, and quadrant diagrams all work — anything Mermaid 10.9 supports.

Code

Fenced blocks get a language label, a copy button, and syntax highlighting. Like Mermaid, the highlighter only loads on pages that need it.

export function slugify(text) {
  return String(text).toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-");
}

Tables

Standard GitHub tables. Wide ones scroll horizontally inside their own container rather than pushing the page sideways.

Headings and the table of contents

## and ### headings get anchor links and populate the "On this page" panel automatically. #### and deeper render normally but stay out of the TOC, which keeps it usable on long pages.