Why Is My Markdown Table Not Rendering?
Few things are more frustrating than pushing documentation to GitHub, GitLab, or your documentation site, only to find raw pipes, broken delimiters, or mangled layouts. Follow this diagnostic manual to identify the root cause and repair your table in seconds.
1. Quick Diagnostic Symptom Tree
Identify your visual symptom in the table below to jump directly to the exact syntax fix:
| What You See in the Browser | Probable Cause | Jump to Fix |
|---|---|---|
| | Header 1 | Header 2 | (Raw pipes shown) | Missing empty blank line before table or bad delimiter row | Fix #1 & #2 → |
| Columns staggered or shifting into next column | Unescaped pipe (|) in cell text or command | Fix #3 → |
| Cell contents pushed to a new row below | Physical Enter newline inside cell text | Fix #4 → |
| Trailing cells chopped off or right borders missing | Ragged rows (mismatched pipe count) | Fix #5 → |
| Table renders inside a gray indented code box | Accidental 4-space tab indentation or inside code block | Fix #6 → |
2. The Top 10 Rendering Failures (Broken vs. Fixed Diffs)
1Missing Blank Line Above the Table (The #1 Offender)
CommonMark and GFM specifications state that a block-level element cannot interrupt an ongoing paragraph without a blank line separating them. If your table directly touches a paragraph or header, the parser treats the pipes as inline text.
| Tier | Price |
| :--- | ----: |
| Pro | $19 |
<!-- blank empty line -->
| Tier | Price |
| :--- | ----: |
| Pro | $19 |
2Missing or Malformed Delimiter Row (Minimum 3 Hyphens Rule)
A Markdown table is defined by its delimiter row (row 2). In standard Markdown, each column in the delimiter row must contain at least three hyphens (---). Two hyphens (--) or an equals sign (===) will cause the entire table to fail rendering.
| :-- | --: |
| John | 28 |
| :--- | ---: |
| John | 28 |
3Unescaped Pipe Characters Inside Cell Text
If your cell text contains an unescaped pipe (such as in regular expressions, bash logic, or mathematical notation), the markdown parser treats it as an unintended column boundary.
| :--- | :---- | :----- |
| Boolean | True | False | Valid |
| :--- | :---- | :----- |
| Boolean | True \| False | Valid |
4Physical Newlines Inside Cell Text
Unlike Google Sheets or Excel, pressing Enter in a text editor produces a real newline character. In Markdown, every newline signifies a brand new table row. Use <br> instead.
| :--- | :------ |
| 1 | Clone repository
Run npm install |
| :--- | :------ |
| 1 | Clone repository<br>Run npm install |
5Ragged Rows (Uneven Column Counts)
If your header has 3 columns, every data row must have 3 columns. Missing trailing cells cause strict parsers (GitLab wiki, Pandoc) to truncate the row or discard cell borders.
| : | : | : |
| 1 | 2 | 3 |
| 4 | 5 |
| : | : | : |
| 1 | 2 | 3 |
| 4 | 5 | |
6Tables Nested Inside Lists or Blockquotes Without Correct Indentation
Nesting a table inside an ordered or bullet list requires aligning every line of the table with the text indentation of the list item (usually 4 spaces). Without this, the parser either drops the list context or renders the table as a literal code block.
1. First step in our setup:
| Env Variable | Default | Purpose |
| :----------- | :------ | :------ |
| `PORT` | `3000` | Local web server port |
2. Second step continues below.3. Platform Compatibility & Quirk Matrix
Markdown implementations differ across platforms. Here is how major developer environments parse table features:
| Platform | Outer Pipes Optional? | <br> in Cells? | HTML <img> in Cells? | <details> in Cells? |
|---|---|---|---|---|
| GitHub (GFM) | Yes | Yes | Yes | No (Breaks row) |
| GitLab (GLFM) | Strict (Requires outer) | Yes | Yes | No |
| Obsidian | Yes | Yes | Yes (Wikilinks too) | Yes |
| Notion | Converts on Paste | Shift+Enter | No (Text only) | No |
| Docusaurus (MDX) | Strict | Yes (<br/>) | JSX tags only | Yes |
Let Our Validator Fix Your Broken Table Automatically
Don't spend hours inspecting raw pipe spacing manually. Paste your broken table into our online Validator to locate exact syntax errors and repair them in 1 click.
Frequently Asked Questions
Why does my table display as raw text and pipes instead of a rendered table?
In over 80% of cases, this happens because there is no blank line immediately before the table. Markdown parsers require an empty line to end a previous paragraph block before initiating a table block. The second most common cause is a missing or malformed delimiter row with fewer than three hyphens per column.
How do I fix ragged rows or uneven column counts?
Ensure that every single row has the exact same number of pipe dividers (|) as your header row. If a cell is empty, insert a space between the pipes "| |" rather than omitting the pipes entirely.
Why does an unescaped pipe break my markdown table layout?
Markdown parsers use vertical pipes (|) exclusively to tokenize columns. If your cell content contains an unescaped pipe (for instance, in regex or shell commands like "grep a|b"), the parser creates an accidental extra column, throwing subsequent row alignments out of phase.
Can I put Markdown tables inside bullet lists or blockquotes?
Yes, but you must indent every single line of the table to align with the list item indentation level (typically 4 spaces or 2 spaces depending on the parser). In blockquotes, every table line must begin with the ">" blockquote marker.
Why do my tables render in VS Code but fail on GitHub or Jekyll?
VS Code uses a forgiving markdown preview parser, whereas GitHub and static site generators (Jekyll, Hugo) use strict CommonMark and GFM compliance engines. Strict engines enforce the preceding blank line rule and require at least 3 hyphens in the separator row.
How can I automatically validate and repair my broken table?
Paste your broken table into our free Markdown Table Validator at /markdown-table-validator/. It scans for 15 common syntax mistakes and repairs delimiter rows, ragged cells, and unescaped pipes with 1 click.