Writing documentation in Markdown

Write documentation in Markdown by giving the page one H1 title, then H2 sections in the order a reader hits them, with fenced code blocks for examples and tables for reference. Keep each section short and answer one question.

A reader came for one thing, and they want to find it fast. Markdown earns its keep here: the same # that marks a heading in the source, or the fenced block that holds a command, also builds the structure a reader skims. Readable source, scannable page, no extra work.

Start with the heading hierarchy

The headings are the skeleton. Get them right and most of the page falls into place.

Use exactly one H1 for the page title. H2 for the main sections. H3 for sub-points inside a section. Don't skip a level to get a smaller font, and don't fake a heading with bold instead of a real ##. A heading carries structure, not styling.

# Acme CLI
 
## Install
 
## Quick start
 
## Commands
 
### deploy
 
### rollback
 
## Configuration
 
## Troubleshooting

A reader sees that outline and knows the shape of the page before reading a word of it. Order the H2s the way someone actually moves through the work: install, run something, look up the details, fix what broke. Reference goes after the getting-started part, not before.

Keep each section short and answer one thing

A section answers one question and stops. When a second topic starts creeping in, give it its own heading.

Lead with the answer, then the detail. Someone who already knows the gist moves on after the first line. Someone who needs more keeps reading. Short paragraphs, one idea each. White space is what makes a docs page skimmable, so spend it freely.

When a section lists steps, number them so a reader can say "I'm stuck on step 3":

## Deploy
 
1. Commit your changes.
2. Run `acme deploy --env prod`.
3. Wait for the green check in the terminal.

Show examples in fenced code blocks

Anything a reader will type or copy goes in a fenced code block, never in plain prose. Three backticks open it, three close it. Add a language name after the opening fence so the block is labeled with what it holds.

```bash
acme deploy --env prod --tag v1.4
```

Use inline code, single backticks, for a filename, flag, or command mentioned mid-sentence: set the --env flag to prod. The backticks keep characters like -- and _ from being read as formatting, and they signal "this is something to type, not something to read."

When you document a config file or a response, show the real thing in a block with the right language label:

```json
{
  "env": "prod",
  "region": "eu-west",
  "retries": 3
}
```

The label names the language, so a reader can tell at a glance whether they're looking at a shell command, a JSON file, or Swift.

Use tables for reference material

A table is the right shape for anything with repeating fields: flags, options, error codes, environment variables. Pipes separate the columns, and a dashed line under the header marks it as a table.

| Flag      | Default | What it does                     |
| --------- | ------- | -------------------------------- |
| `--env`   | `dev`   | Target environment               |
| `--tag`   | latest  | Release tag to deploy            |
| `--retries` | `3`   | Times to retry a failed step     |

That beats three paragraphs each describing a flag. The reader scans the first column, finds their flag, reads across. Keep cells to a short phrase. When a cell wants a paragraph, move it to prose under the table, out of the grid.

Link between pages

Documentation is rarely one page. Link related pages with the standard Markdown link: square brackets for the text, parentheses for the target.

See [Configuration](configuration.md) for the full list of options.
For deploys, read the [Deploy guide](guides/deploy.md).

Write link text that says where it goes. [Configuration](configuration.md) is a good anchor. "Click here" tells the reader nothing. Point at the page that answers the next question a reader will have, right where they'll have it.

A documentation page skeleton

Copy this skeleton and fill it in. It covers the shape most tool or feature docs need:

# Tool name
 
One sentence: what this is and who it's for.
 
## Install
 
```bash
install command here
```
 
## Quick start
 
The shortest path to a working result.
 
1. First step.
2. Second step.
3. What success looks like.
 
## Commands
 
### command-one
 
What it does, then an example.
 
```bash
example here
```
 
## Configuration
 
| Option | Default | What it does |
| ------ | ------- | ------------ |
| key    | value   | description  |
 
## Troubleshooting
 
**Error message here.** What causes it and how to fix it.
 
## See also
 
- [Related page](related.md)

Cut what you don't need, add what you do. The order is the point: title, install, a fast win, the reference, then the help-me-it-broke section at the end.

In Unmarked

Unmarked renders the parts of a doc that do the work, so you can draft and read a documentation page the way it'll actually look.

The outline sidebar turns your heading hierarchy into a clickable list. Add ## and ### sections and they appear in the outline, so you jump straight to "Configuration" or "Troubleshooting" instead of scrolling. The sidebar doubles as a structure check: if the outline reads badly, the page does too.

Fenced code blocks render with their language label, and in Read mode each block gets a copy button, so a reader lifts a command in one click. Write mode dims the syntax until your cursor lands on a line, which keeps the source readable while you draft. Tables render too. In Write mode you build them from the "+ Insert" menu (or ⌥⌘T) instead of aligning pipes by hand.

Split mode shows source and rendered page side by side, scroll-synced. That's the natural way to write docs: you watch the formatting land as you type. Export carries the structure through. Word export builds real heading styles, so the outline works in Word, and PDF export gives tables proportional column widths and keeps code blocks intact.

One thing to expect while you draft: Unmarked opens one document at a time, so the cross-page links you write point at your published site, not at another file inside the app. You write and read each page on its own, then publish the set wherever it lives.