Markdown syntax guide

Markdown lets you write in plain text without giving up useful structure. Each example below shows the rendered result first, followed by the Markdown that creates 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.

Mathematics

KaTeX renders inline math such as $E = mc^2$ and display equations. Use it when notation is part of the explanation rather than an image.

\int_0^1 x^2\,dx = \frac{1}{3}

Markdown source

KaTeX renders inline math such as $E = mc^2$ and display equations.

$$
\int_0^1 x^2\,dx = \frac{1}{3}
$$

Charts and diagrams

Use an echarts fenced block to turn a JSON chart option into an interactive chart. This is useful when a small data story is clearer as a visual than as a table. Diagram blocks render automatically when the post opens.

{
  "tooltip": {
    "trigger": "axis"
  },
  "xAxis": {
    "type": "category",
    "data": ["Jan", "Feb", "Mar", "Apr"]
  },
  "yAxis": {
    "type": "value"
  },
  "series": [{
    "type": "line",
    "data": [120, 180, 150, 260]
  }]
}

Use a mermaid fenced block for diagrams written as text. Mermaid is especially handy for flows, relationships, and other structures that change often.

flowchart LR
    DAO[ENS DAO] --> WG[Working Group]
    WG --> SP[Service Provider]
    SP --> Report[Quarterly Report]

Markdown source

```echarts
{
  "tooltip": {
    "trigger": "axis"
  },
  "xAxis": {
    "type": "category",
    "data": ["Jan", "Feb", "Mar", "Apr"]
  },
  "yAxis": {
    "type": "value"
  },
  "series": [{
    "type": "line",
    "data": [120, 180, 150, 260]
  }]
}
```

```mermaid
flowchart LR
    DAO[ENS DAO] --> WG[Working Group]
    WG --> SP[Service Provider]
    SP --> Report[Quarterly Report]
```

More visual formats

Vega-Lite describes a chart with a concise JSON specification. It is a good fit for declarative data visualizations.

{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {
    "values": [
      { "month": "Jan", "signups": 28 },
      { "month": "Feb", "signups": 45 },
      { "month": "Mar", "signups": 36 },
      { "month": "Apr", "signups": 58 }
    ]
  },
  "width": 360,
  "height": 220,
  "mark": "bar",
  "encoding": {
    "x": { "field": "month", "type": "nominal", "title": null },
    "y": { "field": "signups", "type": "quantitative", "title": "Signups" }
  }
}

Use dot (or graphviz) for Graphviz diagrams. DOT works well when you need explicit graph layout controls.

digraph Launch {
  rankdir=LR;
  node [shape=box, style=rounded];
  Draft -> Review -> Publish;
}

D2 is a modern diagram language for concise architecture and relationship diagrams.

Writer -> Editor: submits draft
Editor -> Site: publishes post
Site -> Reader: delivers article

PlantUML is useful for familiar UML-style sequence diagrams. PlantUML diagrams are generated as SVG by the public PlantUML server when the page loads.

@startuml
actor Reader
participant Site
database Archive

Reader -> Site: Open post
Site -> Archive: Load content
Archive --> Site: Markdown
Site --> Reader: Rendered page
@enduml

Markdown source

```vega-lite
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {
    "values": [
      { "month": "Jan", "signups": 28 },
      { "month": "Feb", "signups": 45 },
      { "month": "Mar", "signups": 36 },
      { "month": "Apr", "signups": 58 }
    ]
  },
  "width": 360,
  "height": 220,
  "mark": "bar",
  "encoding": {
    "x": { "field": "month", "type": "nominal", "title": null },
    "y": { "field": "signups", "type": "quantitative", "title": "Signups" }
  }
}
```

```dot
digraph Launch {
  rankdir=LR;
  node [shape=box, style=rounded];
  Draft -> Review -> Publish;
}
```

```d2
Writer -> Editor: submits draft
Editor -> Site: publishes post
Site -> Reader: delivers article
```

```plantuml
@startuml
actor Reader
participant Site
database Archive

Reader -> Site: Open post
Site -> Archive: Load content
Archive --> Site: Markdown
Site --> Reader: Rendered page
@enduml
```

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