The basic Markdown table
Every Markdown table has three parts: a header row, a separator row of dashes, and your data rows. Pipes (|) separate the cells.
| Work | Owner | Status | | --- | --- | --- | | Outline | Ada | Ready | | Review | Sam | Next |
The columns do not need to line up in the source. Just keep the same number of cells in every row and the renderer draws a neat grid. The pipes at the start and end of each line are optional in many apps, but they make the source easier to read.
Tables are an extension, not part of the original Markdown spec. GitHub, most editors, and Beauty support them, but if a table is going somewhere unusual, check that it renders there.
Align columns with colons
Colons in the separator row set each column's alignment: on the left for left, on both sides for center, on the right for right.
| Item | State | Count | | :--- | :---: | ---: | | Notes | Ready | 12 | | Drafts | Review | 3 |
Left-align text. Right-align numbers so they are easy to compare. Center only short labels; centered sentences are hard to scan.
And keep tables narrow. A small table with a clear job beats a wide grid that makes readers scroll sideways.
Edit tables visually in Beauty
Beauty gives every table real controls. Add or remove rows and columns, set alignment, drag a column to a new position, and resize its width. Press Tab to jump between cells.
When you move a column, its values move with it. After a big rearrangement, a quick glance at the header and the first couple of rows is all the checking you need.
Column widths are a display setting only. Standard Markdown has no way to store widths, so another editor may size the columns differently. If the layout has to stay fixed, export a PDF.
Pipes and long text inside cells
To put a literal pipe inside a cell, escape it with a backslash so it is not read as a column break:
| Expression | Meaning | | --- | --- | | a \| b | Either option |
Keep paragraphs and nested lists out of tables. Markdown tables are best for short values you want to compare: a name, an owner, a status, a price. Longer explanations read better as regular paragraphs below the table.
Pasting a table from Excel, Google Sheets, or a web page? Check the result. Merged cells and rich formatting have no Markdown equivalent.
When to use a table (and when not to)
Use a table when every row answers the same questions. For meeting action items that is "what," "who," and "when," which is exactly how the meeting notes template is set up.
For a loose list of thoughts, bullets are simpler. For steps that connect, a Mermaid diagram shows the relationship better. Pick the simplest structure that does the job.