Welcome — a tour of the writing system

Welcome. This post is a living style guide for the new site. It exercises every component, plugin, and authoring affordance the site supports, so I have a single place to remind myself how to write the next post.

Headings, paragraphs, and inline marks

Each heading on this page has an autogenerated id and an anchor link that appears on hover. Text supports the usual marks: strong, emphasis, inline code, strikethrough, and external links.

Block quotes look like this. They’re sized down a touch and use a left rule in the brand neutral.

— Someone wise

Callouts

Code blocks

Powered by Expressive Code. Plain fenced blocks get language-aware highlighting, copy buttons, and theme-aware colors that follow the site’s light/dark mode automatically.

import { getCollection, type CollectionEntry } from "astro:content";

export type Post = CollectionEntry<"blog">;

export async function getVisiblePosts(): Promise<Post[]> {
    const all = await getCollection("blog", ({ data }) => !data.draft);
    return all.sort((a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime());
}

You can mark a single line, ranges, and add inline annotations:

function add(a: number, b: number): number {
    const sum = a + b; // this line is highlighted
    // these next two are inserts
    if (sum > 100) {
        console.warn("big sum");
    }
    return a + b; // this line is a delete
    return sum;
}

A terminal frame:

npm install
npm run dev

A diff block:

const post = await import(`../../../lib/blog-posts/${params.slug}.md`);
const post = await getEntry("blog", params.slug);

Inline code: write await getCollection("blog") to fetch every post.

Figures and images

Markdown images work as you’d expect:

For more control use <Figure>:

Video

For self-hosted video, use <Video>. It supports posters, autoplay, captions, and a default fallback. Below is a placeholder to show the layout.

For YouTube embeds, the lite-loader from astro-embed keeps the page light until the user clicks play:

Diagrams (D2)

Fenced blocks tagged d2 render to inline SVG at build time via the D2 WebAssembly engine. Zero client JS, zero round trips, no headless browser needed.

Sequence diagrams work too:

Math

Inline math via $...$: the area of a circle is $A = \pi r^2$. Block math via $$...$$:

Charts

<Chart> is a Svelte island. It hydrates only when scrolled into view, so the rest of the page ships zero JS for charts.

Tables, lists, footnotes

Ordered list:

1. Draft the idea.
2. Sketch the structure.
3. Write the first pass without editing.
4. Edit ruthlessly.

Unordered list:

• Keep paragraphs short.
• Lead with the conclusion.
• Use callouts sparingly.
• Show, then tell.

Task list:

• Pick a stack
• Build the design system
• Write more posts
• Ship it

A footnote example.¹

Asides

A horizontal rule

What this is, and isn’t

This page is the source of truth for the writing system. When something stops working, fix it here first — if the welcome page is happy, every other post will be too.