Writing and Understanding Markdown

Markdown adds structure to plain text with a few punctuation marks. Save the source as a .md file; a Markdown viewer turns it into a formatted document.

Everyday syntax

You want	Write this
Main heading	# Garden plan
Section heading	## Materials
Subsection	### Seeds
Bold	**Bring gloves**
Emphasis	*If it rains*
Inline code	`garden.json`
Link	[Read the plan](https://example.com/plan)
Image	
Quote	> Leave room for a path.
Literal asterisks	\*Not emphasis\*

The text inside an image’s square brackets describes it for people who cannot see it. Choose link text that names the destination. CommonMark reference.

Headings and paragraphs

# Garden plan

A short introduction to the project.

## Materials

List what people need before they arrive.

### Seeds

Choose varieties suited to the site.

Put a space after the heading marks. Use heading levels to show structure. A blank line separates paragraphs; a single line break may display as a space. CommonMark specification.

Lists

- Seeds
- Watering can
- Gloves

1. Prepare the soil.
2. Plant the seeds.
3. Water the bed.

Use bullets when order does not matter and numbers for steps. Indent a nested item to align with its parent’s text:

- Tools
  - Spade
  - Watering can

Keep blank lines around lists and other blocks to make the source easier to read.

Code blocks

Wrap several lines of code in a fence of three backticks. A language name can enable syntax highlighting:

```json
{
  "project": "Community garden",
  "active": true
}
```

The fence displays its contents as code. To show an example containing a three-backtick fence, wrap it in four backticks, as this cheatsheet does. Code fence rules.

Tables and task lists

These are Markdown extensions. GitHub Flavored Markdown supports them; other viewers may differ.

| Task | Owner |
| --- | --- |
| Buy seeds | Alex |
| Check water | Sam |

- [x] Choose a site
- [ ] Buy seeds

The separator row makes the first table row a header. Task lists use [ ] for an unchecked item and [x] for a checked item; a viewer may display them without allowing clicks. GitHub Flavored Markdown specification.

Common surprises

• Everything after a code example looks like code: check its closing fence.
• A heading looks like ordinary text: check the space after #.
• A table looks like pipes and dashes: check the separator row and the viewer’s table support.
• A local image is missing: check its path relative to the Markdown file and whether the publishing tool includes it.
• A diagram stays as code: Mermaid needs a viewer that supports diagram rendering; a language label alone does not draw it.

Preview your document in the place people will read it. Standard Markdown travels well; extensions need a check in the destination viewer.