A Markdown table is rows of text separated by pipes (|) with a line of dashes under the header, and it's hard to read raw because the columns rarely line up. To read one, find your column in the header and count pipes across; to edit one, keep the same number of pipes in every row. To stop squinting, open it in a reader that draws it as a grid.
Why are Markdown tables so hard to read?
Markdown tables are hard to read raw because a table's meaning depends on its columns lining up, and raw Markdown tables are almost never aligned. The rest of Markdown is more forgiving: a heading with a # still looks like a heading, and a bullet with a - still looks like a bullet.
| Channel | Spend | Cost per signup | Trend | |---|---|---|---| | Search | $12,400 | $38 | up 14% | | Social | $8,900 | $61 | down 6% | | Newsletter | $2,100 | $19 | up 31% |
| Channel | Spend | Cost per signup | Trend |
|---|---|---|---|
| Search | $12,400 | $38 | up 14% |
| Social | $8,900 | $61 | down 6% |
| Newsletter | $2,100 | $19 | up 31% |
In the raw version on top, your eyes have to count separators to work out which number belongs to which column. Is $61 the spend or the cost per signup for Social? You have to count. In the table underneath, you just look.
Tables are also where the most important information in an AI document tends to live. Plans, budgets, comparisons, owners and dates all end up in tables, because a table is the natural way to compare things. So the hardest part to read is often the part that matters most.
How is a Markdown table built?
Every Markdown table has three parts: a header row, a separator row and the body rows.
- The header row. The column names, separated by pipes.
- The separator row. A line of dashes under each header, also separated by pipes. It tells the app everything above me is a header.
- The body rows. One row per line, with a pipe between each cell.
| Name | Owner | Due |
|------|-------|-----|
| Beta | Maya | Oct 1 |A few details that matter:
- The pipes at the start and end of each row are optional in most apps. You'll see tables written both ways.
- The dashes don't need to match the column width. Three dashes per column is enough.
- Colons in the separator row set alignment.
:---is left,:---:is centered,---:is right. Right alignment is handy for numbers. - A blank line is needed before the table in most apps, or it gets merged into the paragraph above.
Tables aren't part of the original 2004 Markdown. They were added by later versions, most widely through GitHub Flavored Markdown. That's why an older or very simple app might show a table as plain lines of text. What a .md file is has the short history.
How do I read a raw Markdown table in a hurry?
To read a raw Markdown table in a hurry, pick one column from the header and count pipes across to it. These habits help when all you have is the raw text: a code editor, a terminal, or a chat window that didn't format it.
Read the header first, and pick one column
Don't read row by row. Read the header row, decide which column answers your question, and note its position. Due is the third column.
Count pipes, not words
To find the third column in any row, count three pipes in from the left. The text after the third pipe (or after the second, if the row doesn't start with one) is your cell. It's tedious, but it's reliable.
Use the first column as an anchor
The first column is usually the name of the row: the task, the person, the channel. Find the row you care about by its name, then move right.
Widen the window
Raw tables wrap when the window is narrow, and a wrapped row is almost impossible to follow. Make the window as wide as you can, or turn off line wrapping if your app allows it.
Ask the AI to line it up
If you're in a chat, ask: Repeat that table with the columns padded so the pipes line up. AI tools can produce a neatly aligned version, which is far easier to read in plain text.
| Channel | Spend | Cost per signup | Trend |
|------------|---------|-----------------|---------|
| Search | $12,400 | $38 | up 14% |
| Social | $8,900 | $61 | down 6% |
| Newsletter | $2,100 | $19 | up 31% |Aligned tables are much better raw. They're still only readable in a monospace font, and they fall apart the moment someone edits one cell and the widths change.
What does a good Markdown table view do?
A good Markdown table view lines up the columns, marks the header and keeps your eye on the right row. This table lists the quiet work it does and what that lets you do.
| It does this | So you can |
|---|---|
| Lines up every column | Read down a column without counting |
| Makes the header bold with a strong rule | Tell labels from values instantly |
| Adds light stripes or row lines | Follow one row across without drifting |
| Right-aligns numbers | Compare amounts at a glance |
| Wraps long cells inside their column | Read long text without breaking the grid |
| Scrolls sideways on narrow screens | See wide tables on a small window |
| Sorts rows when you click a header | Find the biggest, cheapest or latest without scanning |
None of this changes the file. It's all display. That's why the same table can look awful in one app and perfectly clear in another.
How do I edit a Markdown table without breaking it?
To edit a Markdown table without breaking it, change only the text between two pipes and keep the same number of pipes in every row. You often need to change one cell: a date slipped, an owner changed. These habits keep the rest intact. (For the rest of the file, see how to edit a .md file without breaking it.)
Keep the pipe count the same
Every row must have the same number of cells. If you delete a pipe by accident, every cell after it shifts one column left, and the row falls apart. When you edit, change only the text between two pipes.
Don't worry about alignment
If the table was lined up and your new text is longer, the pipes won't line up any more. That's fine. The table still works. Alignment only matters for reading raw.
Adding a row
Copy an existing row, paste it on a new line below, and replace the text in each cell. Copying keeps the right number of pipes.
Adding a column
Adding a column to a Markdown table is the fiddly one. You need to add a cell to every row, including the header and the separator. Add a pipe and a header name at the end of the header row, add ---| at the end of the separator row, then add a cell to each body row. For big tables, asking your AI to add the column is faster and safer.
Watch for pipes in your text
If a cell needs to contain a pipe character, it will be read as a column break. Write it as \| instead, with a backslash in front.
Line breaks inside a cell
Markdown tables don't allow a real line break inside a cell. Every row has to stay on one line. Some apps accept <br> to force a break inside a cell. If a cell needs paragraphs, it probably shouldn't be a table.
| Task | Owner | Due | |---|---|---| | Search | Sam | Sep 24 | | Beta | Maya | Oct 8 |
| Task | Owner | Due |
|---|---|---|
| Search | Sam | Sep 24 |
| Beta | Maya | Oct 8 |
Which tables do AI tools write most, and how do I read each?
AI tools write five kinds of table most often: comparison, plan, budget, pros and cons, and glossary. Each has a shortcut for reading it.
The comparison table
Options across the top or down the side, criteria in the other direction. Read it by picking the one criterion you care about most and scanning just that row or column. Ignore the rest until you've narrowed the options.
The plan table
Tasks, owners and dates. Read the dates column first to find what's next, then read across for who owns it. If there's a status column, filter by eye for anything not marked done.
The budget table
Items and amounts, often with a total at the bottom. Read the total first, then the biggest numbers. In raw text, right-aligned numbers help a lot, so ask for them.
The pros and cons table
Usually two columns. It's often clearer as two short lists, one headed For and one headed Against. If it's long, ask for the top three of each.
The glossary table
A term and a definition per row. These read far better as a list with the term in bold, especially when definitions run to a sentence or more.
This table sums up what to read first in each type.
| Table type | Read this first | Then |
|---|---|---|
| Comparison | The one criterion that matters most | The options that pass it |
| Plan | The date column | The owner of the next item |
| Budget | The total | The largest lines |
| Pros and cons | The first three of each | Anything that's a deal breaker |
| Glossary | Just the terms | Definitions you don't know |
What prompt makes an AI table easier to read?
Paste this request into Claude, ChatGPT or any AI tool when it gives you a table that's hard to read:
Rewrite that table so it's easy to scan:
- no more than 5 columns
- first column is the name of each row
- numbers right-aligned, in their own columns
- cells under 8 words
- one sentence after it saying what it showsThe result is a table that reads well formatted and survives being read raw.
When is a Markdown table the wrong choice?
A Markdown table is the wrong choice when the content would read better as a list. AI tools sometimes put things in tables anyway, so it's worth asking for something different when:
- Cells contain sentences. If most cells are longer than a few words, a list with a bold label per item is easier to read, raw or rendered.
- There are only two columns. A two-column table of thing and description is often just a list in disguise.
- The table is very wide. More than five or six columns rarely fits comfortably on a screen. Split it into two tables, or flip rows and columns.
- Most cells are empty. A sparse table is a list of exceptions. Write it as a list.
A good test: would you draw this as a grid on paper? If not, it probably doesn't need to be a table.
How do I get AI tools to write better tables every time?
To get better tables from Claude, ChatGPT or another AI tool every time, put the rules from the prompt above into your standing instructions, such as custom instructions or a project's instructions. Then you don't have to ask after each table.
The rule to add one sentence after each table is especially useful for visual readers. A sentence like Newsletter is the cheapest channel by a wide margin tells you where to look before you look.
What do the square brackets under an AI table mean?
The square brackets under an AI table are a Markdown task list: - [x] is done and - [ ] is not. AI plans often combine a table of workstreams with a checklist of next steps. In raw text, a long checklist is a column of brackets that all look the same. In a reader, you get ticked boxes and, in some apps, a progress bar that tells you how many are done.
- [x] Agree on channels - [x] Set the budget - [ ] Brief the designer - [ ] Book the launch post
- Agree on channels (done)
- Set the budget (done)
- Brief the designer (to do)
- Book the launch post (to do)
How do I copy an AI table into Word or a spreadsheet?
To copy an AI table into Word, copy it from a formatted view, not from the raw text. Pasting raw Markdown into Word gives you rows of pipes. Copying the drawn table from a chat window or a reader usually pastes as a real table. How to paste AI text into Word covers the details, including what to do when the formatting breaks.
For a spreadsheet, ask the AI for the same table as CSV (comma-separated values), save it as a .csv file, and open that in Numbers or Excel.
How does One Clear Reader show Markdown tables?
One Clear Reader draws Markdown tables as grids with a header row and columns that line up, so you can read down or across without counting. A few extras help with big AI tables:
- Sort by any column. Click a header to sort the rows, click again to reverse them, and a third time to put them back. Amounts like $12,400 sort as numbers. It only changes what you see. The file stays as it was.
- Wide tables scroll sideways. When a table is wider than the page, More columns buttons (‹ ›) let you move across it. Full View gives the page the whole screen, and wide tables spread out to use it.
- Copy the table. With Pro, the CSV and Markdown buttons copy a table ready for a spreadsheet or another document.
- CSV files open as tables too. A .csv or .tsv file opens as one sortable table, free.
When you need to change a cell, open the Markdown source (free), change the text between the pipes, and save. Before anything is written, One Clear Reader shows you the lines you changed, and the table redraws once the save is done. With Pro you can skip the pipes: in the visual editor, type into the cells and add rows or columns, and One Clear Reader saves the table back as Markdown. Either way, the file stays a .md your AI can read again.
Questions people ask
How do you make a table in Markdown?
To make a table in Markdown, write the header row with pipes between column names, add a separator row of dashes, then add one line per row with pipes between cells. Leave a blank line before the table.
Why isn't my Markdown table showing as a table?
A Markdown table usually fails to show because of a missing blank line above it, a missing separator row, or an app that doesn't support tables. Rows with different numbers of cells can also break it.
Can a Markdown table cell have more than one line?
No, a Markdown table cell can't hold a real line break, because each row must stay on one line. Some apps accept a br tag to force a break inside a cell.
How do I align numbers to the right in a Markdown table?
To right-align numbers in a Markdown table, put a colon at the right end of that column's dashes in the separator row, like ---: .
Can I merge cells in a Markdown table?
No. Markdown tables are simple grids without merged cells. For complex layouts, use two tables or a spreadsheet.
Can I sort a Markdown table?
No, not inside the .md file itself. The rows stay in the order they were written. Some readers let you click a header to sort what you see, and One Clear Reader does this without changing the file.