Common Markdown Formatting Issues and Fixes

Markdown is loved for its simplicity, but that simplicity can be deceptive. Because there isn't one single "official" specification (though CommonMark is the standard), different renderers can interpret your text in surprising ways.

In this guide, we'll look at the most common "broken" Markdown symptoms and provide the "Golden Rules" to fix them forever.

1. The "Ghost" Table

Symptom: You typed out a table, but it just appears as a jumble of pipes and text in the preview.

The Fix: Tables are sensitive to two things: white space and headers.

1. Empty line before: Always leave a full empty line before your table starts.
2. The Separator Row: You must have a row of dashes (---) immediately after your header row.
3. Consistent Pipes: While not strictly required by all renderers, starting and ending every row with a pipe (|) ensures much higher compatibility.

| Header 1 | Header 2 |
|----------|----------|
| Content 1| Content 2|

2. Invisible Line Breaks

Symptom: You pressed Enter, but the text is still on the same line in the output.

The Fix: In Markdown, a single newline is often ignored to allow for "hard wrapping" in text editors.

1. Paragraphs: Press Enter twice to create a new paragraph.
2. Hard Line Breaks: If you want to move to the next line without a full paragraph gap (useful for addresses or poetry), end the line with two spaces before hitting Enter.

3. Nested List Confusion

Symptom: Your sub-bullets are appearing as main bullets or just plain text.

The Fix: Indentation is key. Most renderers require exactly four spaces (or one tab) of indentation for each level of nesting.

1. Use the same character (don't mix tabs and spaces).
2. Ensure there is a space after the bullet character (- or *).

4. Broken Images and Links

Symptom: You see the alt text but not the image, or the link doesn't click.

The Fix:

1. Check your brackets: It's [Link Text](URL). If you forget the parentheses or use curly braces, it won't work.
2. Escaping special characters: If your URL contains parentheses, the Markdown parser might get confused. Use %28 and %29 instead of ( and ) in the URL itself.
3. Relative Paths: If converting to PDF, ensure your image paths are absolute or correctly relative to the file's location.

5. Bold/Italic "Bleeding"

Symptom: You started a bold section, and now half your document is bold.

The Fix: Markdown symbols must touch the text they are formatting.

• Wrong: ** this is not bold **
• Right: **this is bold**

Conclusion

Most Markdown "bugs" are actually just missing spaces or extra newlines. By following these strict formatting rules, you'll ensure that your documents look perfect across all platforms—from GitHub to MarkdownPDFConverter.com.