How to Write Markdown Tables, Task Lists, and More

The Markdown features that make documents readable

Most Markdown is headings, paragraphs, and lists. But the features that make a document genuinely scannable — the ones that turn a wall of text into something a reader can navigate in seconds — are tables and task lists. A well-placed table conveys a comparison faster than three paragraphs. A task list shows progress at a glance.

Both are GitHub Flavored Markdown extensions, and both are easy once you know the rules. This guide covers how to write them well, how to nest lists, and how to fix the common breakages. You can test every example in a Markdown viewer.

Writing Markdown tables

A GFM table is a grid built from pipes and hyphens. The first row is the header, the second row is the separator, and the rest are data.

| Tool | Format | Best for |
| --- | --- | --- |
| Markdown to PDF | PDF | Final deliverables |
| Markdown to HTML | HTML | Web and CMS |
| Markdown to Word | DOCX | Review and edits |

The pipes on the left and right edges are optional, but including them makes the source easier to read and edit.

Column alignment

The separator row controls alignment with colons:

| Left aligned | Center aligned | Right aligned |
| :--- | :---: | ---: |
| a | b | c |

• :--- left
• :---: center
• ---: right

Alignment is visual only — it does not change the data, but it makes numeric columns easier to scan when right-aligned.

Three table mistakes that break rendering

Tables are the element most likely to render as raw text. Watch for these:

1. No blank line before the table. A table glued to the paragraph above it often fails to render. Always leave a blank line.

   Here is a comparison:
   
   | A | B |
   | --- | --- |
   | 1 | 2 |
   

2. Inconsistent column counts. Every row must have the same number of columns as the header. An extra or missing pipe breaks the row.

3. Pipes inside cell content. A literal | inside a cell confuses the parser. Escape it as \| when you need one.

If your table shows up as raw pipes instead of a grid, the cause is almost always a missing blank line above it.

Writing task lists

A task list is a bulleted list with checkboxes. Use - [ ] for open and - [x] for completed:

## Launch checklist

- [x] Write the release notes
- [x] Update the docs
- [ ] Tag the release
- [ ] Announce it

Task lists render as interactive-looking checkboxes and are ideal for READMEs, issues, and any progress tracker. They work in ordinary bulleted lists; mixing them with regular bullets is fine.

Nesting lists

Lists can nest. Indent the child item (usually two or four spaces) to place it under a parent:

1. Set up the project
   - Initialize the repo
   - Add a README
2. Build the feature
   - Write the code
   - Add tests
3. Ship it

Two rules keep nested lists clean:

• Use the same indentation for every item at the same level.
• Keep nesting shallow — two levels is usually enough. Deep nesting is hard to read and easy to break.

Ordered vs unordered lists

Choose by meaning, not habit:

A common mistake is using ordered lists for everything. If the steps are not sequential, bullets are clearer — they signal "these are equivalent."

Code blocks inside lists

Code blocks work inside lists if you indent them to match the list item:

1. Install the package:

   ```bash
   npm install

2. Start the server:

   npm start
   

The key is aligning the code fence with the list item's text. Misaligned fences break out of the list and start a new top-level block.

## Mixing elements for scannable docs

The most readable documents combine these elements deliberately. A status section might use a heading, a task list, and a table together:

```markdown
## Status

- [x] Design approved
- [ ] Build started
- [ ] QA pending

## Owners

| Area | Owner |
| --- | --- |
| Frontend | Ana |
| Backend | Ben |

That structure lets a reader scan status in one glance and find an owner in the next — far faster than reading two paragraphs.

Test and convert your tables

Tables and task lists survive conversion to other formats, which is what makes them so valuable:

• Tables stay tables in Markdown to HTML and Markdown to PDF
• Task lists render in Markdown to Word
• Both display correctly in any full-GFM Markdown viewer

Write them well once, and they carry through every export.

Write your first table now

Open the Markdown viewer, paste the table and task-list examples from this guide, and watch them render. Once they look right, you can convert that same content to HTML, PDF, or Word without changing a line.