What is Markdown?

A Markdown table is rows of pipe-separated cells with a dashed rule under the header. Alignment is set by placing colons in that rule.

Who uses it

README files, GitHub issues, documentation sites, Obsidian and Notion.

Reading Markdown

Leading and trailing pipes are optional and both are handled. A pipe the author escaped with a backslash is read as data rather than a column break, which is the usual reason a hand-written table parses one column too wide.

Writing Markdown

Cells are padded so the source lines up in a plain text editor, pipes inside values are escaped, and line breaks inside a cell become <br> because a Markdown table row cannot span lines.

What it can hold

Markdown is a markup language. A pipe table is one row per line, so a line break inside a cell ends the row early. A machine can read it back, but only by following the conventions rather than a rule the format enforces.

It keeps

A header that is marked as one, rather than being the first row by convention.

It cannot express

Types. Every value is text. A column of digits is indistinguishable from a column of numbers until something downstream decides to read it as one, which is where a leading zero usually disappears.
A null. An absent value and an empty one look the same, and nothing in the file says which was meant.
Nesting. Cells are flat, so structured values have to be flattened into extra columns or written into one cell as text.
A line break inside a cell. One would end the row, so it has to be replaced before writing.

What it looks like

Example Markdown

| id  | name             | role          | started    | hours |
| --- | ---------------- | ------------- | ---------- | ----- |
| 007 | Halima Yusuf     | Analyst, data | 2024-03-15 | 38.5  |
| 012 | Jonah "Jo" Pryce | Engineer      | 2025-11-02 |       |
| 104 | Wei Chen         | Manager       | 2023-06-30 | 40    |

Questions

Can a Markdown table cell contain a line break?

Not directly. The row ends at the newline. Use a <br> tag inside the cell, which every common Markdown renderer passes through to the HTML output.

How do I open Markdown files?

Any text editor will show you the contents. To read it as a table, paste it into the converter on this site and it appears in an editable grid. Nothing is uploaded.

Is Markdown a good format for sharing data?

It depends who is receiving it. README files, GitHub issues, documentation sites, Obsidian and Notion. If the recipient is outside that group, a plain CSV travels further than anything else.