Documentation 2026-03-10

Fix Markdown Rendering & Preview Errors

Fix Markdown formatting that doesn't render: broken headings, unformatted code blocks, broken lists, link issues, and table alignment problems.

📝 Tool: Markdown Preview — Free

Markdown is forgiving but has quirks around whitespace, blank lines, and code fence variants. Here are the most common Markdown rendering issues and how to fix each one.

Jump to error

  1. 1 Heading `#` not rendered
  2. 2 Code block not syntax-highlighted
  3. 3 List items not rendered as a list
  4. 4 Link renders as raw Markdown text
  5. 5 Table renders but columns are misaligned
1

Heading `#` not rendered

Error message
(No error — # appears as literal text)
Root cause

Headings require a space between `#` and the text, and the `#` must be at the start of a line with no preceding space.

Step-by-step fix

  1. 1 Ensure there's a space after `#`: `# Heading` not `#Heading`.
  2. 2 Ensure the line starts at column 1 (no leading spaces).
  3. 3 Add a blank line before the heading if it follows a paragraph.
Wrong 
#Title
  ## Subtitle
Correct 
# Title

## Subtitle
2

Code block not syntax-highlighted

Error message
(Code appears as plain text, no syntax coloring)
Root cause

Inline backtick code (`` `code` ``) is for inline snippets. For multi-line blocks, use triple backticks with an optional language identifier.

Step-by-step fix

  1. 1 Use triple backticks ` ``` ` on their own lines.
  2. 2 Specify the language after the opening backticks: ` ```python `.
  3. 3 Ensure no trailing spaces after the opening backtick fence.
  4. 4 Alternatively, indent with 4 spaces (standard Markdown code block).
Wrong 
`print('hello')`
Correct 
```python
print('hello')
```
3

List items not rendered as a list

Error message
(Dashes appear as literal dashes, not bullet points)
Root cause

Lists require a blank line before the first item when following a paragraph. Also, mixed indentation (tabs vs spaces) breaks nested lists.

Step-by-step fix

  1. 1 Add a blank line between the preceding paragraph and the list.
  2. 2 Use consistent indentation: 2 or 4 spaces for nested items.
  3. 3 Avoid mixing tabs and spaces.
Wrong 
Here are items:
- First
- Second
Correct 
Here are items:

- First
- Second
5

Table renders but columns are misaligned

Error message
(Table shows but columns overlap or appear wrong)
Root cause

The separator row between headers and data must contain at least three dashes `---` per column. Column counts must be consistent.

Step-by-step fix

  1. 1 Ensure every row has the same number of `|` separators.
  2. 2 The separator row must use `---`, `---:`, or `:---:` (with optional colons for alignment).
  3. 3 The pipe `|` at the start and end of rows is optional but must be consistent.
Wrong 
| Name | Age |
| Alice | 30 |
Correct 
| Name  | Age |
|-------|-----|
| Alice | 30  |

Frequently Asked Questions

Why does my Markdown render differently on GitHub vs the preview tool?

GitHub uses GitHub Flavored Markdown (GFM) which adds tables, task lists, and auto-links. The preview tool uses standard CommonMark. For GitHub specifically, test in a gist or repo README.

How do I add a line break without creating a new paragraph?

End a line with two or more spaces, then press Enter. This creates a `
` tag. Alternatively, use `\` at the end of the line (supported in CommonMark).

Related Tools

±
Text Diff Checker
Compare texts & find differences
Wc
Word & Character Counter
Count words, chars & reading time
&;
HTML Entity Encoder
Encode & decode HTML entities

Try the Markdown Preview now

Free, runs in your browser, no signup required. Learn more about Markdown Preview.

Open Markdown Preview →
← All Troubleshooting Guides