A simple guide to Markdown

Markdown lets you concentrate on a sentence while a few familiar symbols give it structure. This blog starts with ordinary Markdown and adds a small set of reading components: a note, a collapsible explanation, a set of tabs, or a quick question.

This is a beginner's tour. Each example shows the source first and the result immediately after it. The illustration, checklist, and quiz are demonstration material, ready to adapt to your own writing.

Give a thought some structure

Use ## for a section and ### for a subsection. The article title already comes from its settings, so you do not need to repeat it as a # heading. Section headings also help readers navigate with the floating outline.

### A small observation

A short paragraph is often enough to explain one idea.

Leave a blank line before starting the next paragraph.

A small observation

A short paragraph is often enough to explain one idea.

Leave a blank line before starting the next paragraph. A normal line break in the source does not create a new paragraph; the empty line does.

Emphasis, links, and quotations

Use bold for a key phrase, italics for a quiet emphasis, and inline code for something readers might type. Strikethrough can show a correction without erasing its context.

Keep **one clear idea**, add *a little emphasis*, and use `code` for literal text.

An ~~early guess~~ improved explanation can stay visible.

Explore [the archive](/archive/) when you want another page to read.

> A useful note begins with something worth noticing.

Keep one clear idea, add a little emphasis, and use code for literal text.

An early guess improved explanation can stay visible.

Explore the archive when you want another page to read.

A useful note begins with something worth noticing.

The text inside square brackets names a link; the destination goes in parentheses. Use the Studio link tool to choose a local post or file instead of guessing its address. A draft needs to be published before its link can work on the public site.

Lists that stay readable

Use a dash for an unordered list and numbers for a sequence. Indent a nested item beneath its parent. A task list adds [ ] or [x]; it records progress in your source rather than acting as a reader-editable to-do app.

- Notice a detail.
- Ask a question.
  - Keep it small enough to explore.

1. Write a first version.
2. Read it once more.

- [x] Add a useful heading.
- [ ] Find a clearer example.

• Notice a detail.
• Ask a question.
  • Keep it small enough to explore.

1. Write a first version.
2. Read it once more.

• Add a useful heading.
• Find a clearer example.

Definitions and footnotes

A definition list keeps a term beside its explanation. A footnote gives a supporting detail somewhere to live without interrupting the paragraph.

Markdown
: Plain text with a little structure.

A note can carry a supporting detail.[^small-detail]

[^small-detail]: Footnotes can contain **emphasis** and links.

Markdown

Plain text with a little structure.

A note can carry a supporting detail.¹

Footnote definitions can sit at the end of your source. Their labels are names you choose; the rendered article supplies the numbers and return links.

Code you can copy

Wrap code in three backticks. Add the language for syntax highlighting, an optional title for context, and an optional line selection in braces.

```javascript title="greeting.js" {2}
const subject = 'reader';
console.log(`Hello, ${subject}!`);
```

const subject = 'reader';
console.log(`Hello, ${subject}!`);

The copy button copies the code itself. Line numbers and the filename stay in the presentation. To show a three-backtick example inside a code block, surround the example with four backticks, as this guide does in its source.

Tables with a quiet rhythm

Separate columns with pipes. The second row defines alignment: :--- for left, :---: for centered, and ---: for right. Right alignment is useful for numbers.

| Feature | Source | Examples |
| :------ | :----: | -------: |
| Heading | `##`   |        2 |
| List    | `-`    |        3 |
| Link    | `[]()` |        1 |

The blog uses restrained horizontal rules rather than a box around every cell. Wide tables scroll within the article on small screens. Write a literal pipe inside a cell as \|. For a caption and notes, place one table inside :::table[Your caption] and close it with :::.

Images that leave room for the words

An image uses an exclamation mark followed by a description and its address. The description is alternative text: describe what matters in the image rather than its filename. Studio uploads provide a local /media/ address.

A figure adds a caption and optional display limits. This example caps the width at 480 pixels and the height at 320 pixels, while keeping the complete image in proportion.

:::figure[A page ready for a new idea]{width="480" max-height="320" align="center"}
![An open notebook with blue lines and a small leaf beside it](/media/markdown-guide-notebook.svg)
:::

These are display limits, so the image can shrink further on a phone. They do not resize the downloadable file. Open the image to inspect it in the shared viewer; ordinary Markdown images use that viewer too.

Notes, tips, and small warnings

Components use colon fences. Open with :::name[Optional title], write ordinary Markdown inside, and close with :::. Keep a blank line around the component so its boundaries are easy to see.

:::tip[Start small]
One useful example is better than an unfinished catalog.
:::

You can also choose note, important, warning, or caution to match the message. A note adds context; a warning calls attention to a consequence.

GitHub-style callouts such as > [!TIP] are supported as well. Use these components sparingly so their meaning remains easy to recognize.

Extra detail, available when needed

A details component keeps an optional explanation behind a native disclosure. Readers can open it with a pointer or keyboard.

:::details[Why use a disclosure?]
It keeps optional context nearby without interrupting the main explanation.
:::

Steps, questions, and answers

Use steps when the order matters. Use question and answer components to make a short exchange easy to find.

:::steps
1. **Write.** Put one idea into words.
2. **Preview.** Read the result as a visitor would.
3. **Refine.** Remove what does not help.
:::

:::question[Do I need to learn every component?]
Can I begin with paragraphs and headings?
:::

:::answer[Yes, begin there]
Add a component when it helps explain the idea.
:::

Two views of the same idea

Rich tabs can hold Markdown, including lists and code. Give the outer container four colons so its three-colon children have clear boundaries.

::::tabs
:::tab[The idea]
Keep **one thought** in each paragraph.
:::

:::tab[The checklist]
- Name the idea.
- Give an example.
- Read it aloud.
:::
::::

Readers can switch panels with the tabs. Without JavaScript, both panels remain readable, so no explanation disappears.

Small inline details

These short directives add meaning within a sentence. An abbreviation carries an expanded title, while keyboard labels distinguish a key from ordinary prose.

Keep :mark[the key phrase] visible. Press :kbd[Enter] to continue.

:abbr[SVG]{title="Scalable Vector Graphics"} stays sharp when enlarged.

Water is H:sub[2]O, and a square is written x:sup[2].

Keep the key phrase visible. Press Enter to continue.

SVG stays sharp when enlarged.

Water is H₂O, and a square is written x².

A little math

Put a short expression between single dollar signs. For a centered display, put double dollar signs on their own lines, above and below the expression.

If $x=3$, then $x^2=9$.

$$
\frac{1}{2}+\frac{1}{4}=\frac{3}{4}
$$

If , then .

Use braces to group a fraction's numerator and denominator. The project renders equations with MathJax 4 during preview and builds; readers receive the typeset result without downloading the math renderer.

One quick check

A small quiz uses an interactive code fence containing JSON. The answer counts from zero: 0 is the first choice, 1 the second. Keep the explanation useful even when someone chooses the wrong option.

```interactive
{
  "type": "quiz",
  "title": "A heading or a paragraph?",
  "prompt": "Which source creates a section heading?",
  "choices": ["## A small idea", "**A small idea**", "`A small idea`"],
  "answer": 0,
  "explanation": "Two hash marks followed by a space create a level-two heading."
}
```

Choose an answer and check it, or open the explanation directly. The explanation also remains available without JavaScript.

Keep the useful parts close

In Studio, use Insert component to choose a supported example. Split or Preview mode lets you read the result while editing; source preferences can also show image and math previews. The syntax checker helps catch an unclosed container or an invalid quiz before publication.

Start with a paragraph, a heading, and one example. The rest can wait until the writing needs it.