OmniDocHow to Write a Table in Markdown
Learn how to make a table in Markdown by hand, with header rows, dash separators, column alignment, and fixes for tables that won't render.
If you have ever pasted a grid of data into a README or a note and watched it turn into a jumble of pipes and dashes, you already know why people search for how to make table in Markdown. Markdown has no drag-and-drop grid. A table is plain text: vertical bars separate the cells, and a row of dashes tells the renderer where the header ends. Once you know the three parts, you can write one in a minute or two and check it by eye before you publish.
This guide covers the raw syntax you type by hand: the header row, the separator row, alignment, and the common mistakes that stop a table from rendering. It doesn't cover converting an existing Word or spreadsheet table. If that is your job, use a conversion tool first, then come back here to clean up the output.
How do you make a table in Markdown? The short answer
Write a header row with the column names separated by vertical bars, add a separator row of dashes beneath it, then add one line per data row with the same number of cells.
| Your situation | What to do | Why |
|---|---|---|
| You need a simple table in a README or document | Use the three-part pattern: header, dashes, rows | Renderers look for the dash row to know a table starts |
| You want numbers or dates to line up | Add colons to the dash row, such as :--- or ---: | Alignment is set only in the separator row |
| A cell must contain a literal vertical bar | Put a backslash in front of the bar | An unescaped bar starts a new column |
| Your table shows up as plain text | Check for a missing dash row or uneven cell counts | Both are common reasons a table fails to render |
| Your editor reflows or rewraps text | Turn off automatic wrapping for that file | A wrapped row no longer sits on one line |
Before you start
A few checks save time later. Each one takes a few seconds.
- Confirm the destination supports tables. Core Markdown does not define tables, but many platforms add them. Where tables aren't supported, your rows show up as ordinary text with visible bars. Reason: the same source can look correct in one place and broken in another.
- Use a plain text editor or the source view. Rich text editors can convert your characters or hide the syntax. Reason: you need to see exactly the bars and dashes you typed.
- Plan your columns before typing. Decide the column names and how many you need. Reason: every row must have the same number of cells as the header.
- Keep each row on one line. A table row is a single line of text. Reason: a line break inside a cell usually breaks the table, and standard syntax doesn't offer a reliable way to add one.
- Decide alignment for each column. Reason: alignment is set once per column in the separator row, so it's easier to plan it than to fix it later.
Writing a Markdown table by hand, step by step
- Write the header row. Type each column name between vertical bars. A row like
| Item | Quantity | Notes |gives you three columns. Starting and ending the row with a bar is optional, but it makes rows easier to scan. - Add the separator row. Directly under the header, type at least three dashes for each column, separated by bars. For the header above, use
| --- | --- | --- |. This row must have the same number of cells as the header. - Set alignment if you need it. A colon at the left of the dashes means left alignment, colons at both ends mean center, and a colon at the right means right alignment. For example,
| :--- | :---: | ---: |left-aligns the first column, centers the second, and right-aligns the third. Columns with no colon are left-aligned by default. - Add the data rows. Each row gets the same number of cells as the header. For an empty cell, leave the space between the bars blank, but keep the bars in place so the count stays correct.
- Format text inside cells if needed. Bold, italic, and inline code generally work inside a cell. Keep each cell short, because long text makes the source hard to edit even when it renders.
- Escape any literal vertical bar. If a cell must show a bar character, put a backslash in front of it. Without the backslash, the bar is read as a column boundary.
- Leave a blank line before and after the table. On many renderers, a table that touches the paragraph above or below it can merge with that text.
Here is a finished example. Notice that the center and right alignment only changes how the columns look, not how the source is typed:
| Item | Quantity | Notes |
|---|---|---|
| Notebook | 2 | A5, lined |
| Pen | 10 | Blue ink |
| Stapler | 1 |
Check the result
Once the table is in your document, check it where readers will see it. Source view and rendered view can disagree, so look at both if you can.
| Check | How to see it | If it's wrong |
|---|---|---|
| The table renders as a grid | Preview the file in the place you publish it, or in a Markdown viewer | Confirm the dash row exists and sits directly under the header |
| Every row has the same number of columns | Count the cells in each row against the header | Add or remove bars so every row matches |
| Alignment matches your plan | Look at the rendered columns | Recheck the colons in the dash row |
| No cell splits unexpectedly | Look for stray text landing in a new column | Escape the bar with a backslash |
| Text above and below is intact | Look at the lines just before and after the table | Add a blank line on each side of the table |
If the table still won't render after these checks, simplify it. Remove the formatting from the cells, rebuild the header and dash rows from scratch, and add the rows back one at a time. This quickly shows which row is causing the problem.
❓ FAQ
1. Do the vertical bars need to line up?
No. Lining up the bars helps you read the source, but renderers ignore the extra spaces. A table with uneven spacing renders the same way as a neatly padded one.
2. Why does my table show up as plain text?
The usual causes are a missing dash row, a header and dash row with different cell counts, or a platform that doesn't support tables. Check those three before you change anything else.
3. How do I put a line break inside a table cell?
Standard Markdown doesn't provide a reliable way to do this inside a table cell. Shorten the text or split the content across more rows. Some platforms accept their own break tag, but support varies, so test it before you rely on it.
4. Can I write a Markdown table in an online editor?
Yes. The UniDoc web editor at app.unidoc.top supports Markdown, so you can type the same syntax there. Check the rendered result before you share the document, since it may differ from the platform where your readers will see it.
📝 Summary
A Markdown table is a header row, a dash separator row, and data rows, all divided by vertical bars. Keep the cell counts matching, set alignment in the dash row, and check the rendered table where readers will see it. With that pattern in mind, you'll know how to make table in Markdown for any simple grid of information.
