Markdown PDF Formatting Not Working? Here's How to Fix It

If your Markdown PDF output has broken tables, plain-text code blocks, missing images, or wrong heading sizes, the problem is almost always in the Markdown source — not the converter. The live preview shows you exactly what the PDF will look like before you download. Fix the preview and the PDF will be correct.

Here are the most common Markdown PDF formatting problems and the specific fix for each one.

Fix: Code Blocks Showing as Plain Text in the PDF

If your code appears as normal body text instead of a formatted code block, check the fencing syntax. Code blocks require three backtick characters on their own line above and below the code — with nothing else on those lines (except an optional language tag after the opening backticks).

Common causes:

• Only two backtick characters instead of three on either side
• Backticks on the same line as the first or last line of code
• Spaces before the opening backticks (which some parsers treat differently from a fenced block)
• Using apostrophes or single quotes instead of backtick characters

Check the live preview: a correctly fenced code block shows with a monospace font and light gray background. If it looks like plain text in the preview, the same will appear in the PDF.

Fix: Table Not Rendering — Appears as Pipe Characters and Dashes

Markdown tables fail to render for three main reasons:

1. Missing separator row: The second row must contain only dashes and pipes: |---|---|. Without it, nothing renders as a table.
2. Uneven column count: Every row (including the separator row) must have the same number of pipe-separated columns. A row with 3 columns and a separator with 2 will break rendering.
3. No blank line above the table: The table needs a blank line separating it from any paragraph above it.

The separator row dashes don't need to match the column width exactly — |---| works just as well as |---------|. What matters is that each column has at least one dash and the pipe count matches.

Sell Custom Apparel — We Handle Printing & Free Shipping

Fix: Images Not Showing in the PDF

Images in Markdown PDFs are loaded from their URLs at the time of PDF generation. If an image doesn't appear in your PDF:

• URL is not publicly accessible: The image must be at a public URL — not a local file path, not a file on your computer, not a URL behind a login.
• URL contains spaces: Replace any spaces in the URL with %20
• Broken alt text syntax: The format is ![alt text](url) — the exclamation mark before the bracket is required. Without it, the Markdown renders as a link, not an image.
• HTTP vs HTTPS: Use https:// image URLs — some browsers block loading http:// images in secure contexts.

Check the preview: if the image doesn't appear in the live preview, it won't appear in the PDF either. Debug using the preview before downloading.

Fix: Headings Wrong Size or Rendering as Plain Text

Heading problems in PDF output usually trace back to one of these:

• No space after the hash: #Title won't render as a heading — use # Title
• Too many hash symbols: Markdown only supports H1 through H6. Seven or more hashes typically render as plain text.
• No blank line before the heading: A heading immediately following body text with no blank line above it may render as a paragraph continuation on some parsers.

In the PDF output, headings follow a size hierarchy: H1 is largest, H2 is medium, H3 is smaller but still clearly a heading. If all your headings look the same size, check that you're using #, ##, and ### correctly rather than all the same level.

Fix: Bold and Italic Not Showing in PDF

Bold and italic formatting requires asterisks directly adjacent to the text — no space between the marker and the word.

• Broken bold: ** bold text ** (spaces after opening asterisks) → doesn't render on most parsers
• Working bold: **bold text** → renders as bold
• Mixed markers: Opening with asterisks and closing with underscores won't close correctly

Verify quickly: paste a single word wrapped in double asterisks into the live preview. If it renders bold there, the PDF will match.

Frequently Asked Questions

If the preview looks correct, will the PDF always match?

In almost all cases, yes. The PDF is generated from the same rendered HTML you see in the preview. Minor differences can occur around page breaks and how very long tables or images near page edges are handled.

Why does my Markdown render correctly in GitHub but look wrong in the PDF?

GitHub uses its own Markdown flavor (GFM) with its own CSS. The PDF uses standard Markdown rendering with generic styling. Content structure should match — differences are usually in font choices and specific visual styling rather than structural rendering.

My entire document looks like plain text with no formatting — what went wrong?

Check that you're using standard Markdown characters. Content written in a rich-text editor may contain smart quotes or other non-standard characters that interfere with Markdown parsing.

Can I add custom CSS styling to fix the PDF appearance?

This tool uses a preset style for clean output. For custom CSS, use a local Markdown editor like VS Code with the Markdown PDF extension, which allows custom stylesheets.