Markdown syntax guide

Markdown keeps writing close to plain text while still giving each idea useful structure. Each section below shows the rendered result first, followed by the Markdown source that produces it.

Text and links

Use strong text when a phrase matters, emphasis for a lighter stress, and ~~strikethrough~~ when something is no longer true. Use inline code for a short command such as npm run build.

Links can point to another page, such as the complete archive, or to an external resource like Astro.

Markdown source

Use **strong text** when a phrase matters, *emphasis* for a lighter stress,
and ~~strikethrough~~ when something is no longer true. Use inline code for
a short command such as `npm run build`.

Links can point to another page, such as the [complete archive](/archive),
or to an external resource like [Astro](https://astro.build).

Lists

An unordered list works well for related ideas:

Write the first draft.
Read it aloud.
- Shorten the slow parts.
- Keep the useful detail.
Publish when it is clear.

Use a numbered list when order matters:

Create a Markdown file.
Add its frontmatter.
Write and publish the post.

Task lists are useful for a small checklist:

Choose a topic
Draft the article
Ask for feedback

Markdown source

An unordered list works well for related ideas:

- Write the first draft.
- Read it aloud.
  - Shorten the slow parts.
  - Keep the useful detail.
- Publish when it is clear.

Use a numbered list when order matters:

1. Create a Markdown file.
2. Add its frontmatter.
3. Write and publish the post.

Task lists are useful for a small checklist:

- [x] Choose a topic
- [x] Draft the article
- [ ] Ask for feedback

Quotes and code

Make the simple thing easy, and the hard thing possible.

— a useful rule for writing and interfaces

Use fenced code blocks for longer snippets. The language after the opening fence enables syntax highlighting.

const recentPosts = posts
  .filter((post) => !post.data.draft)
  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf())
  .slice(0, 5);

console.log(`Showing ${recentPosts.length} recent posts.`);

Markdown source

> Make the simple thing easy, and the hard thing possible.
>
> — a useful rule for writing and interfaces

```js
const recentPosts = posts
  .filter((post) => !post.data.draft)
  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf())
  .slice(0, 5);

console.log(`Showing ${recentPosts.length} recent posts.`);
```

Tables and images

Tables make comparisons easier to scan:

Syntax	Best for
`# Heading`	Sections and hierarchy
`> Quote`	A cited idea or callout
`code`	Commands and short identifiers

Images use the familiar alt-text-and-URL form. Alt text describes the image for readers who cannot see it.

Markdown source

| Syntax | Best for |
| --- | --- |
| `# Heading` | Sections and hierarchy |
| `> Quote` | A cited idea or callout |
| `` `code` `` | Commands and short identifiers |

![The site's minimal A favicon](/favicon.svg)

Footnotes

Footnotes let a paragraph stay readable while keeping supporting context nearby.¹

Markdown source

Footnotes let a paragraph stay readable while keeping supporting context nearby.[^1]

[^1]: This is a footnote. The link returns to the reference in the paragraph above.

This is a footnote. The link returns to the reference in the paragraph above. ↩