If a Markdown table renders as plain text, shifts columns, or stops halfway through, the cause is usually syntax, an unescaped pipe, a blank line, or renderer differences.
Contents (10)
A Markdown table can fail in several different ways: it may render as plain text, shift columns, stop halfway through, or work on one platform but not another.
The first thing to know is that tables are not part of every Markdown implementation. GitHub Flavored Markdown (GFM), for example, adds table syntax on top of the CommonMark base.
So troubleshooting should separate two questions:
- Is the table syntax valid for the renderer you are using?
- Does the platform where you will publish support that table syntax?
Start with the smallest valid table
Before rewriting a large table, reduce it to a minimal example:
| Item | Status |
| --- | --- |
| A | Done |
| B | Pending |
If that works, add your original rows and formatting back gradually.
For a quick browser check, Markdown Viewer can render a .md file or pasted Markdown without requiring an account. It is useful for isolating whether the problem is in the Markdown itself before you test the final publishing platform.
Cause 1: the header and delimiter rows do not match
If the whole block stays as plain text, check the first two rows.
This is invalid for a two-column header:
| Name | Status |
| --- |
| A | Done |
Use the same number of cells in the header and delimiter row:
| Name | Status |
| --- | --- |
| A | Done |
GitHub's table syntax uses a delimiter row of hyphens under the header cells. Colons can be added for alignment:
| Left | Center | Right |
| :--- | :---: | ---: |
| A | B | C |
If the renderer does not recognize the delimiter row, it will not recognize the block as a table.
Cause 2: a cell contains an unescaped pipe character
The pipe character | separates table cells.
If you want a literal pipe inside a cell, writing it directly can create an extra column.
Problematic:
| Symbol | Meaning |
| --- | --- |
| | | separator |
Escaped:
| Symbol | Meaning |
| --- | --- |
| \| | separator |
This comes up often with regular expressions, shell commands, code snippets, or syntax documentation.
Cause 3: the delimiter row is not Markdown table syntax
A line that looks visually like a separator is not enough.
This will not be treated as a GFM table delimiter:
| Item | Status |
| = | = |
| A | Done |
Use hyphens:
| Item | Status |
| --- | --- |
| A | Done |
When debugging, remove decorative formatting and return to the simplest valid structure.
Cause 4: a blank line or another block ends the table
A blank line can terminate the table block.
For example:
| Item | Status |
| --- | --- |
| A | Done |
| B | Pending |
The row after the blank line is no longer part of the same table.
This is easy to introduce when copying Markdown from an AI assistant or another editor. If a table breaks halfway through, inspect the raw lines around the failure point.
Cause 5: you are trying to put block content inside a cell
Markdown tables are best for compact, inline content.
Long multi-paragraph content, nested block elements, or complex line breaks inside a cell are not portable across renderers.
If a cell needs several paragraphs, lists, or large code blocks, the document is usually easier to maintain if that explanation moves below the table.
Cause 6: the syntax is valid, but the target platform uses a different Markdown flavor
This is one of the most common sources of confusion.
GFM extends CommonMark with features such as tables and task lists. Another Markdown renderer may use a different extension set or disable tables entirely.
That means a table can be valid GFM and still fail elsewhere.
For a GitHub README, do the final check on GitHub. For a blog platform or CMS, use that platform's own preview before publishing.
A generic renderer is useful for the first question—"is the Markdown itself behaving as expected?"—but the destination platform is the final authority for its own rendering.
For a general browser-preview workflow, see Preview Markdown in Your Browser.
Diagnose the symptom instead of rewriting everything
| Symptom | First thing to inspect |
|---|---|
| Entire table is plain text | Header row, delimiter row, renderer support |
| Columns shift partway through | Unescaped |, inconsistent cells |
| Table ends early | Blank line or another block |
| Works on one site but not another | Markdown flavor / renderer differences |
| Long cells render strangely | Line breaks or block content inside cells |
Different symptoms usually point to different causes. Reducing the table to a minimal case is faster than changing the whole document at once.
A practical debugging workflow
- Copy only the broken table.
- Paste it into Markdown Viewer.
- Reduce it to a header, delimiter row, and one data row.
- Confirm that it renders as a table.
- Add rows and special characters back one at a time.
- Once the Markdown works, test it in the final publishing platform.
This separates a syntax problem from a platform-specific rendering problem.
Summary
If a Markdown table does not render, start with the header and delimiter row. If columns shift, look for literal pipe characters. If the table stops halfway through, check for blank lines or another block.
If the same Markdown behaves differently across platforms, the problem may be the Markdown flavor rather than the table itself.
Reduce the table to the smallest working version, confirm it in a renderer, then rebuild it piece by piece.