Markdown You Will Actually Use

Use this post as a cheat sheet for the prose surface. Open it in two windows: source on one side, rendered post on the other.

Headings

Start posts at ##. The page title is the only h1.

Inline text

The inline elements the theme styles:

Renders as:

A link, bold, italic, inline code, ⌘ + K, and highlighted text.

Use for a phrase that needs attention inside a paragraph. For a whole block, use a callout.

Lists

Ordered when sequence matters, bullets otherwise.

Nested lists work, but keep them shallow:

• Section
  • Subsection
  • Another subsection
• Section

Quotes

Blockquotes are styled as a pause, not as general emphasis.

A writing surface should disappear while the reader moves through it.

With attribution:

Don't communicate by sharing memory, share memory by communicating.
— Rob Pike

Tables

For compact reference data:

Element	Use
Heading	Structure the article
Quote	Pause on a specific idea
Code	Show exact commands or values

If a table needs sorting or interaction, move it outside the article.

Code blocks

Always add the language. Highlighting is provided by astro-expressive-code with the bundled tone-cold theme.

ts const site = { title: 'Astro Tone' };

Renders as:

Terminal:

JSON config:

Astro components use the same surface:

Images

Reference images from src/assets/ with a relative path. Astro processes them at build time (resize, AVIF/WebP, dimensions emitted in the markup).

Optional caption goes here.

Click an image in a rendered post to open the lightbox. Text in italics immediately after the image is treated as the caption.

Callouts

Plain HTML with classes. The theme styles three tones:

Small HTML you can use inline

CSS is the language that carries most of the visual system. H₂O and x² read naturally inline. Press Esc to close any open dialog in the theme.

Dividers

Use a divider only when a section break needs more force than a heading.

---

Footnotes

The first half of the work is easy.

Keep footnotes short. If a note grows past a sentence, put it in the body.

What the theme does not style

If you use

, , or outside a callout, default browser styling applies. Either add your own CSS in src/styles/prose.css` or wrap the element in an MDX component.