Markdown Tables: A Practical Guide
Tables are one of the most useful Markdown features for notes: comparisons, schedules, checklists with columns and quick reference data. The syntax is simple once you see it.
Basic syntax
Tables are part of GitHub Flavored Markdown and are supported by most modern Markdown editors. Columns are separated by pipes (|), and a row of dashes separates the header from the body:
| Task | Owner | Status |
| ----------- | ----- | ----------- |
| Draft brief | Sam | Done |
| Review copy | Alex | In progress |
The pipes at the start and end of each line are optional, but including them makes tables easier to read as plain text.
Alignment
Add colons to the separator row to align columns:
| Left | Centre | Right |
| :--- | :----: | ----: |
| a | b | 10 |
Right alignment is handy for numbers, so the digits line up.
Formatting inside cells
You can use inline formatting in cells: **bold**, *italic*, `code` and links all work. Block elements such as lists, headings and multi-line paragraphs generally do not. If you need a line break inside a cell, some renderers accept <br>, but support varies.
Escaping pipes
If a cell needs to contain a literal pipe character, escape it with a backslash: \|.
The columns don't have to line up
Markdown does not care whether the pipes line up vertically. This is valid:
| Name | Value |
|---|---|
| Width | 200 |
Lining them up just makes the raw text nicer to read. Many editors can format tables for you.
Tips for readable tables
- Keep tables narrow. Three to five columns are easy to read; ten are not.
- Keep cell text short. Move long explanations into a paragraph below the table.
- Put the most important column first.
- Use a table for genuinely tabular data, not for page layout.
Writing tables in your notes
GlissNotes is a free, local-first Markdown notes app for Mac, Windows, the web and Android. Its rich view renders tables while the underlying note stays plain Markdown, and you can switch to the plain or code view at any time to edit the raw syntax.