The 3 Most Common Markdown Mistakes That Break Your README
A missing space after a hash. A table with one extra pipe. A code block without a blank line. A preview catches them before you push.
I used to convert Markdown to HTML by pushing to GitHub and hoping it rendered correctly. If the table was broken, I pushed again. A Markdown preview tool would have caught every mistake before the first push.
Markdown is simple until it is not. A missing space after a hash mark. A table with the wrong number of pipes. These errors are invisible in raw text and obvious in a preview.
The Missing Space After the Hash
I wrote ##My Heading instead of ## My Heading. GitHub renders it as plain text. The preview shows this instantly. Counter-intuitive: the most common Markdown error is not forgetting the syntax. It is forgetting the space between the syntax and the text.
The Table With One Extra Pipe
Four columns but five pipes in the separator row. The entire table broke. One missing or extra pipe destroys the entire structure.
The Code Block Without a Blank Line
Some parsers require a blank line before code blocks. Without it, the code gets merged into the previous paragraph. The free Markdown preview supports GitHub Flavored Markdown. Write and preview before pushing.
Tools mentioned in this article
Markdown Preview
Write Markdown on the left, see formatted HTML on the right. Live preview updates as you type. Supports GitHub-flavored Markdown including tables, code blocks, and task lists.
JSON Formatter
Format, validate, and beautify JSON with syntax highlighting and collapsible tree view. Minify to a single line for production. Catches syntax errors with line numbers.
Text Diff Checker
Compare two pieces of text side by side and see exactly what changed. Highlights additions, deletions, and modifications. Drop in old and new versions to spot edits.