Markdown tables

A table: the minimal example#

| Topic | Status | Problems solved |
| --- | --- | --- |
| Fractions | done | 24 |
| Percentages | in progress | 7 |

The first line is the header. The second, made of hyphens, is required: it is what turns a set of lines into a table. Data rows follow. When rendered, you get an ordinary table with a bold header row and three columns; extra spaces around cell text disappear, so you can line up the pipes in the source however you like — it does not affect the result.

People usually write three hyphens per column in the separator, although formally one is enough. What really is required is that the number of columns in the separator matches the header: an extra or missing column breaks the whole table. The outer pipes at the start and end of a line are optional, but they make the table easier to read in the source.

An important caveat: tables are not part of the core CommonMark specification — they are an extension (GitHub Flavored Markdown) supported by GitHub, GitLab and most editors. In a home-grown or stripped-down renderer a table may stay as lines with pipes, and that is not a mistake in your markup.

Aligning columns#

Alignment is set with colons in the separator line:

| Topic | Date | Hours |
| :--- | :---: | ---: |
| Exponents | 12 Sep | 3 |
| Equations | 5 Oct | 12 |

A colon on the left aligns the column to the left, colons on both sides centre it, a colon on the right aligns it to the right. Numeric columns are almost always right-aligned: that way digits of the same place line up and numbers are easy to compare by eye.

You cannot break a line inside a cell: every table row is one line of source. If the text is long, use <br> — but it only works where HTML inside Markdown is allowed (GitHub allows it, strict renderers do not) — or move the details below the table. A pipe inside a cell is escaped with a backslash — \| — otherwise it splits the cell in two.

Tables are handy for notes where every entry has the same fields: a rule on the left, an example on the right. For instance, notes on special products in algebra fit in two columns — the formula and the typical mistake.

Headings#

A heading is hashes at the start of a line, a space, then the text. One hash is the top level (# Heading), two is the second level, and so on up to six. The space after the hashes is required: without it the line stays plain text.

## Section

### Subsection

This renders as a second-level heading with a third-level heading inside it. Do not skip levels: after the second comes the third, not the fifth — otherwise the table of contents that many renderers build automatically breaks.

There is a second way to write headings — underlining a line with equals signs or hyphens. That creates an unexpected trap: a line of three hyphens directly under a paragraph turns that paragraph into a heading instead of drawing a horizontal rule. To get a rule, leave a blank line before the hyphens.

Lists#

- first item
- second item
  - nested item

1. numbered item
2. another one

A bulleted list starts with a hyphen, an asterisk or a plus — all three give the same result, but stick to one within a document. A numbered list is a number, a period and a space. Nesting is done with an indent of two to four spaces; tabs do not work everywhere, so spaces are safer.

A list needs a blank line before it. Without one, the paragraph and the list stick together into one block of text with hyphens — the most common complaint about "broken markup".

Numbers are recalculated when rendering: you can write 1 for every item and the list still comes out numbered in order. That is handy when items move around a lot.

Links and images#

Text with a [link](https://commonmark.org/) inside.

![Solution diagram](diagram.png)

A link is text in square brackets and the address in round ones. An image is the same with an exclamation mark in front; the text in brackets becomes the alt text for people who cannot see the image. If the address contains spaces, wrap it in angle brackets or replace each space with %20.

A missing exclamation mark is why "a link appeared instead of the image". The markup is valid; it just describes something else.

Code, quotes and task lists#

Inline code goes between single backticks. A code block is three backticks before and after, and after the opening three you write the language so highlighting is correct:

```python
print("hello")
```

A quote is a greater-than sign at the start of a line:

> A quote that takes
> two lines.

It renders as a block with a vertical bar on the left. A blank line inside breaks the quote in two, so put the sign on every line.

A task list is an extension you know from GitHub:

- [ ] learn the laws of exponents
- [x] solve five equations

Brackets with a space inside give an empty checkbox, brackets with an x give a ticked one. The space between the brackets is required: without it the line stays an ordinary list item.

What else to remember#

A single line break inside a paragraph disappears when rendered — the text is joined into one paragraph. To force a break, put two spaces at the end of the line or a backslash.

Italic is text between single asterisks, bold between double ones. An asterisk, hash or underscore that must stay a literal character is escaped with a backslash.

Markdown is designed so the source reads well without rendering. If a file is hard to read in a plain text editor, it has too much markup — usually a sign that a table should be split in two or long text moved out of its cells.

Step-by-step plan

1. Step 1 — a three-row tableWrite a header, a separator and two data rows; check the column counts match.
2. Step 2 — alignmentAdd colons to the separator and right-align the numeric column.
3. Step 3 — the rest of the markupWrite a page with headings, a list, a link, an image and a code block.
4. Step 4 — the trapsCheck blank lines before lists and tables, and escaping of pipes and asterisks.
5. Step 5 — previewCompare the source with the rendered result in your editor and fix the places where the markup did something else.

Check yourself

Sources

• Markdown GuideA syntax reference with extensions and examples
  free
• GitHub Docs: Organizing information with tablesTables as GitHub renders them
  free
• CommonMarkThe core syntax specification and a sandbox for testing markup
  free

Was this helpful?

Yes No