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.

## Section

### Subsection

Inline text#

The inline elements the theme styles:

A [link](https://astro.build), **bold**, _italic_, `inline code`,
<kbd>⌘</kbd> + <kbd>K</kbd>, and <mark>highlighted</mark> text.

Renders as:

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

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

Lists#

Ordered when sequence matters, bullets otherwise.

1. First step.
2. Second step.
3. Third step.

- One useful example
- One clear tradeoff
- One next step

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.

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

With attribution:

> Don't communicate by sharing memory, share memory by communicating.<br>
> — <cite>Rob Pike</cite>

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:

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

Terminal:

npm run build

JSON config:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

Astro components use the same surface:

---
const title = 'Quiet defaults';
---

<section class="intro">
  <h2>{title}</h2>
  <slot />
</section>

Images#

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

![Description for screen readers](../../assets/tone-sample-blue-architecture.jpg)
_Optional caption goes here._

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:

<div class="callout callout-note">
  <p>Use for extra context.</p>
</div>

<div class="callout callout-tip">
  <p>Use for a small recommendation.</p>
</div>

<div class="callout callout-warning">
  <p>Use for limits or likely mistakes.</p>
</div>

Small HTML you can use inline#

<abbr title="Cascading Style Sheets">CSS</abbr>

H<sub>2</sub>O · x<sup>2</sup>

Press <kbd>Esc</kbd>

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.[^1]

[^1]: The second half is what actually ships.

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 <details>, <summary>, or <aside> 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.