How to Write Markdown Tables: Pipes, Hyphens, Alignment, and Line Breaks

When you want to organize and present items in a README, documentation, or a blog post, the Markdown table is handy. Without writing an HTML <table> tag, you can build a readable table with rows and columns just by lining up pipes (|) and hyphens (-). This article explains, with examples, everything from the basic structure of a Markdown table to column alignment, handling line breaks and pipes inside cells, and how rendering differs across services.

The Basic Structure of a Markdown Table

A Markdown table is made of three elements: the header row, the separator row, and the data rows. Look at the example below.

| Item | Price | Stock |
| --- | --- | --- |
| Apple | 100 | Yes |
| Orange | 80 | No |

This renders as follows.

The first line is the header, and the second line is the separator row made of hyphens. This separator row is what tells Markdown to treat the block as a table. The third line onward is the actual data. Each cell is divided by a pipe; the leading and trailing pipes can sometimes be omitted, but keeping them makes the source easier to read and prevents misinterpretation.

Writing it by hand one character at a time easily causes misalignment, so a good way to grasp the structure is to enter values into the Markdown Table Generator, output the result, and observe the generated code.

Pipe and Hyphen Notation Rules

There are a few rules for displaying a table correctly. Let us go through them in order.

• The separator row is required: directly below the header row, you need a separator row containing at least one hyphen (-) per column. Without it, the block is treated as a plain paragraph.
• The number of columns is set by the pipes: the number of cells in the separator row defines the column count. Match the header and data rows to it.
• The number of hyphens is free: --- or a single - both work. Many people align the widths to make the source look tidy, but it does not affect the rendered result.
• Spaces inside cells are ignored: extra spaces before and after a cell are trimmed when rendered, so feel free to use them to align widths in the source.

In short, the spaces and hyphen counts you use to tidy the source code do not affect the final output. Formatting for readability makes later edits easier.

Left, Center, and Right Alignment: The Colon Position

Each column can have its text alignment set by the position of the colon (:) in the separator row. Aligning numbers such as prices or quantities to the right lines up the digits and makes them easier to read.

It helps to remember that you place the colon on "the side you want the text to align to." A colon on the left means left-aligned, colons on both ends mean centered, and a colon on the right means right-aligned. An actual separator row looks like this.

| Item | Price |
| :--- | ---: |
| Apple | 100 |

In this case the "Item" column is left-aligned and the "Price" column is right-aligned. Alignment is specified independently per column, so you can mix alignments across the columns of a table.

Line Breaks and Pipe Escaping Inside Cells

Two things beginners often stumble on are line breaks inside cells and handling the pipe character.

When you want a line break inside a cell

Inside a table cell, simply adding a line break in the source has no effect. To insert a line break within a single cell, use the HTML <br> tag. For example, writing Line 1<br>Line 2 displays two lines within the cell.

When you want a pipe inside a cell

The pipe (|) is the cell separator, so writing it directly splits the column. To display a pipe as a character inside a cell, escape it with a backslash as \|. When showing code, writing it inside inline code wrapped in backticks can sometimes remove the need to escape.

• Line break: use <br> (a source line break does nothing)
• Pipe: escape it as \|
• Emphasis and styling: notations like **bold** and `code` also work inside cells

Tables with lots of long text or code are prone to missed escapes when written by hand. If you enter the content into the Markdown Table Generator and output it, you can leave the separator row and pipe formatting to the tool.

How Rendering Differs on GitHub and Notion

Markdown tables differ a little in support and rendering depending on the service. Let us cover the differences among representative environments.

The point to note is that tables are an extension not included in the original Markdown standard. Many environments support them, starting with GFM (GitHub Flavored Markdown), but older tools or minimal converters may render tables broken. Some services like Notion automatically convert pasted Markdown into their own table blocks, after which you edit within that service\'s UI. For long documents, building a table of contents from your headings with the Markdown TOC Generator alongside your tables helps readers grasp the overall structure.

Tips for Clean Tables and Common Mistakes

Finally, here are tips for keeping tables clean and the points people often trip over.

• Do not forget the separator row: most cases where a table fails to form are due to a missing separator row. Always place it directly below the header.
• Match the column counts: if the header, separator, and data rows have different cell counts, the table breaks. For empty cells, leave the content blank but keep the pipes.
• Add blank lines around the table: without blank lines before and after, the table may merge with the preceding paragraph and not be recognized.
• Do not force manual formatting: width alignment is only for readability and does not affect rendering. If it is tedious, leave it to a tool.

Once you remember two symbols, the pipe and the hyphen, plus colon-based alignment, anyone can quickly write Markdown tables. Start with a small table, and revisit this article when you need line breaks or pipe escaping. To check actual output, use the Markdown Table Generator, and pair it with the Markdown TOC Generator to organize headings in long documents for greater efficiency.

Please note that this article is intended to provide general information. The behavior of Markdown tables can vary by the service or converter version you use, so make your decision after checking the latest official information and documentation.