Getting Markdown tables and code blocks to look right in a PDF

A practical guide · about 4 min read

Two things break more often than anything else when you turn Markdown into a PDF: tables and code blocks. Either your table prints as a line of pipes and dashes, or your code loses its spacing and colour. Both problems have the same root cause, and both are easy to avoid once you know what to look for.

Why tables break

The original Markdown spec, written in 2004, has no tables at all. Tables come from a later extension called GitHub-Flavored Markdown (GFM). So when a converter prints your table as raw text like this:

| Item | Qty |
|------|-----|
| Pen  | 3   |

…it means the converter is reading plain Markdown and doesn't know about the GFM table extension. The fix isn't to change your table — your table is fine. The fix is to use a converter that understands GFM. Most modern ones do, including this one.

Aligning columns

Once tables work, you can control alignment with colons in the separator row. This is especially useful for numbers, which read better right-aligned:

| Item    | Qty | Price |
|:--------|----:|------:|
| Cable   |  10 | $2.50 |
| Adapter |   4 | $7.00 |

That renders as:

• :--- left-aligns (the default)
• ---: right-aligns
• :--: centres

Keeping wide tables on the page

A table with too many columns will run off the edge of an A4 or Letter page. There's no magic fix for this — paper is only so wide. Practical options: cut columns you don't need, switch to landscape if your tool allows it, or split one wide table into two narrower ones. As a rough rule, 6–7 columns is the most that stays comfortable on a portrait page.

Why code blocks break

Code has two needs: keep the exact whitespace, and stay readable. Both come down to using a fenced code block — three backticks before and after — rather than indenting by hand:

```js
function total(items) {
  return items.reduce((sum, x) => sum + x.price, 0);
}
```

Naming the language after the opening fence (js, python, bash, and so on) lets the converter apply syntax highlighting. If your code comes out as a single grey block with no colour, the converter isn't running a highlighter — the code is still correct, just harder to read. A tool with highlighting built in will colour keywords, strings and comments automatically.

Long lines

Code doesn't wrap the way prose does. A very long line will either be clipped at the page edge or force a horizontal scroll that doesn't exist on paper. If you control the source, break long lines yourself. If you don't, pick a slightly smaller font or narrower margins so more fits per line.

A quick checklist

• Tables printing as pipes? Your converter doesn't support GFM — switch tools.
• Numbers looking messy? Right-align the column with ---:.
• Table running off the page? Drop columns or go landscape.
• Code with no colour? Use fenced blocks and name the language.
• Code clipping at the edge? Shorten long lines or narrow the margins.

Get those right and the PDF will look like something you actually wrote on purpose, not a raw text dump.