3 Markdown Mistakes I Fixed After Previewing My Drafts

3 Markdown Mistakes I Fixed After Previewing My Drafts

I write in Markdown every day — READMEs, Dev.to posts, GitHub issues, documentation. I thought I knew the syntax cold. Then I started previewing my drafts before publishing and realized I was making the same three mistakes over and over.

Here's what I caught, and how you can avoid them.

1. Tables That Look Fine in Raw Markdown — But Break on Render

This is the most common one. You write a table like this:

| Name | Type | Default |
|------|------|---------|
| timeout | number | 30 |
| retries | number | 3 |

Looks perfect. But then you add a fourth column to one row without updating the header separator line — and suddenly GitHub renders a broken mess. The separator line needs exactly the same number of pipes as every other row. Miss one, and the table falls apart.

Fix: Always preview your tables. A real-time preview catches misalignment instantly — you'll see the render fail while you're still editing, not after you've pushed to main.

2. Code Blocks That Eat Your Backticks

You want to show a literal backtick inside a code block. Standard Markdown uses triple backticks for code fences, but what if your code contains triple backticks? The renderer gets confused about where the code block ends.

The original Markdown spec says: Use \`backticks\` for inline code.

json
{
"example": "this is inside a fenced code block"
}

markdown

In the raw editor, this looks fine. But the renderer sees the first

, then the inner

json starts a nested fence (or ends the outer one early). The result is half your content vanishing from the rendered output.

Fix: Use four backticks for the outer fence when your code contains triple backticks. Or better — preview it. You'll see the break immediately.

3. Numbered Lists That Reset (When You Don't Want Them To)

You write:

1. Install dependencies
2. Configure the environment

Some paragraph in between.

3. Run the app
4. Open localhost:3000

Markdown sees that paragraph as a list break. Items 3 and 4 start a new list — so they render as "1. Run the app, 2. Open localhost:3000" instead of continuing the numbering. This is correct per the spec, but it's rarely what you intended.

Fix: Indent the paragraph with four spaces to keep it inside the list item, or indent the continuation numbers. Or just preview it — the reset will jump out at you.

The Lesson: Preview Before You Publish

All three of these mistakes look correct in raw text. That's the trap — Markdown is designed to be readable in source form, so errors are invisible until you render them.

I now paste every README update, every Dev.to draft, and every documentation change into a Markdown preview tool before pushing. It's a free, client-side tool — nothing leaves your browser — and it catches these formatting bugs in seconds. The split-pane view (edit on the left, preview on the right) makes it obvious when a table misaligns, a code fence breaks, or a list resets unexpectedly.

If you write Markdown regularly, make previewing a habit. Five seconds of checking beats a pull request comment pointing out your broken table.