Converting Markdown to PDF should be simple. But when your code blocks lose syntax highlighting, tables break at page edges, or images disappear entirely, it can be frustrating.

This guide covers 5 common formatting issues and how to fix them — so your PDF looks exactly like your Markdown.

Issue 1: Code Blocks Lose Syntax Highlighting

The Problem: Your beautifully highlighted code in Markdown becomes plain, unstyled text in the PDF.

# Before (Markdown)
```javascript
function hello() {
  console.log("Hello, World!");
}

After (PDF) — No colors, no styling

### Solution A: Use a Converter That Supports GFM

Many converters only support basic Markdown, not GitHub Flavored Markdown (GFM) with syntax highlighting.

**Fix:** Use [MD2PDF Online](/md-to-pdf) which renders code blocks with proper highlighting for 50+ languages including:
- JavaScript, TypeScript, Python
- Go, Rust, Java, C++
- HTML, CSS, SQL, JSON
- Bash, PowerShell

### Solution B: Use Pandoc with Highlighting

```bash
# Install Pandoc (if not already)
brew install pandoc

# Convert with syntax highlighting
pandoc input.md -o output.pdf --highlight-style=tango

Available styles: pygments, kate, monochrome, espresso, zenburn, haddock, tango

Solution C: Specify Language in Code Block

Always add the language identifier after the backticks:

```javascript  ← Add language name
const x = 10;
```

Without the language identifier, most converters won't apply highlighting.

Issue 2: Tables Break Across Pages

The Problem: Long tables split awkwardly in the middle, with half on one page and half on the next.

Solution A: Keep Tables Short

If possible, redesign tables to be shorter. Consider:

• Splitting one large table into multiple smaller tables
• Removing unnecessary columns
• Using lists instead of tables for simple data

Solution B: Use Pandoc LaTeX Settings

pandoc input.md -o output.pdf --pdf-engine=xelatex

XeLaTeX handles tables better than the default engine, keeping rows together when possible.

Solution C: Use an Online Converter

MD2PDF Online automatically adjusts table formatting for page breaks, preventing mid-row splits.

Issue 3: Images Don't Appear in PDF

The Problem: Your Markdown has images, but the PDF shows blank spaces or broken links.

Solution A: Check Image Paths

Markdown images work differently depending on the path type:

Path Type	Example	Works In
Relative	./images/demo.png	Local files, same folder
Absolute URL	https://site.com/img.png	Online converters, web
GitHub relative	images/demo.png	GitHub only

Fix: Match your path to your conversion method:

• Online converter: Use absolute URLs or upload images together
• Local Pandoc: Use relative paths from the same directory

Solution B: Download Images Locally

For GitHub READMEs with relative images:

# Clone the entire repository (includes images)
git clone https://github.com/user/repo.git

# Convert from the repo directory
cd repo
pandoc README.md -o README.pdf

Solution C: Use an Online Tool with Image Support

MD2PDF Online handles:

• Relative images (when uploaded together)
• Absolute URLs (from any domain)
• GitHub-hosted images

Just upload your .md file along with any local images.

Issue 4: Links Are Not Clickable

The Problem: Your Markdown links [text](url) appear as underlined text but don't open when clicked in the PDF.

Solution A: Check PDF Reader Settings

Some PDF readers disable links by default. Try:

• Adobe Acrobat: Enable "Links" in preferences
• Chrome: Links work automatically
• Preview (Mac): May not support all link types

Solution B: Use a Proper Converter

Some converters render links as plain text. MD2PDF Online and Pandoc both generate clickable links by default.

Solution C: Verify Link Format

Ensure your Markdown links are correct:

# Correct formats
[Link text](https://example.com)
[Link with title](https://example.com "Click here")

# Common mistakes
[Link text] (https://example.com)  ← Space breaks the link
[Link text](example.com)           ← Missing protocol (https://)

Issue 5: GitHub-Specific Syntax Not Working

The Problem: Features like task lists, strikethrough, and autolinks don't render in the PDF.

GFM Feature	Syntax	Renders In
Task lists	- [x] Done	GitHub, some converters
Strikethrough	~~removed~~	GitHub, GFM converters
Autolinks	https://example.com	GitHub, some converters
Tables	| col | col |	GitHub, most converters

Solution: Use a GFM-Compatible Converter

MD2PDF Online supports full GitHub Flavored Markdown:

• ✅ Task lists render as checkboxes
• ✅ Strikethrough works
• ✅ URLs auto-link
• ✅ Tables with alignment

Quick Troubleshooting Checklist

Before converting, check these common issues:

Check	Fix
Language specified in code blocks?	Add javascript, python, etc. after backticks
Images in same directory?	Move images to same folder as .md file
Using relative image paths?	Change to absolute URLs for online converters
Links formatted correctly?	No spaces between ] and (
GFM syntax supported?	Use a GFM-compatible converter

Which Converter Handles Formatting Best?

Feature	MD2PDF Online	Pandoc	VS Code Extensions
Syntax highlighting	✅ 50+ languages	✅ Multiple styles	✅ Limited
Tables	✅ Auto page break	✅ LaTeX handling	⚠️ May break
Images	✅ Relative + URL	✅ Relative only	⚠️ Varies
Clickable links	✅	✅	✅
GFM support	✅ Full	✅ With extensions	⚠️ Partial
Setup	None	Install required	Install required

Recommendation:

• No setup needed: Use MD2PDF Online for best formatting out of the box
• Full control: Use Pandoc with custom settings for professional documents

Frequently Asked Questions

Why does my code block show as plain text?

Most likely you forgot to add the language identifier after the opening backticks. Change:

const x = 10;

To:

```javascript
const x = 10;

### How do I keep images from disappearing?

1. For online converters: Use absolute URLs (`https://...`)
2. For local conversion: Keep images in the same folder as your `.md` file
3. For GitHub READMEs: Clone the whole repo to get image files

### Can I customize code block colors?

Yes, with Pandoc you can choose highlighting styles:

```bash
pandoc input.md -o output.pdf --highlight-style=espresso

With MD2PDF Online, the default style is optimized for readability with a clean, modern color scheme.

Why is my table too wide for the page?

Wide tables overflow the page margins. Solutions:

• Reduce column content
• Split into multiple tables
• Use Pandoc with --pdf-engine=xelatex for better handling

Does the converter preserve Markdown comments?

No. Markdown comments (<!-- comment -->) are stripped during conversion in most tools. If you need notes in your PDF, use blockquotes instead:

> This is a note that will appear in the PDF.

---

Next step: Try converting your Markdown with MD2PDF Online and see if these formatting issues are resolved. If you encounter new problems, the live preview lets you adjust before exporting.