Markdown to PDF: tables, diagrams and equations
Three block types cause most of the damage in a PDF: wide tables, Mermaid diagrams that arrive as images, and equations that depend on fonts. Here is what breaks first and the order to fix it in.
On this page
Why these three break first
A screen reflows; a PDF page does not. Anything whose size you did not decide — a table that is wider than the text block, a diagram rendered at whatever width the container had, a formula built from fonts that may not be installed — gets resolved at export time by something other than you. The result is usually not an error. It is a page that prints wrong or reads wrong.
The failure modes, side by side
| Block | Typical failure | What to change |
|---|---|---|
| Wide table | Columns squeeze or spill past the margin; a header row is lost after a page break | Fewer columns, shorter cell text, keep the header table-wide consistent |
| Mermaid diagram | Rendered as an image: the text inside it stops being selectable and searchable | Keep labels short, give it its own paragraph, write alt text |
| Equation | Glyphs fall back to a font that lacks them, or the formula is too wide for the page | Check the glyphs after export, or use the formula-heavy engine |
| Long document | No page numbers or TOC, so a reviewer cannot cite a page | Enable the TOC and page numbers before exporting |
Tables that survive a page break
Most table damage is width, not syntax. If a table has more than six columns on A4, no exporter can keep it readable at body-text size — cut columns first, then shorten cells. Keep the header row identical across every row of the table (a row with more cells than the header is the most common cause of a broken grid), and avoid nesting tables: an inner table is the one structure that reliably defeats both print layout and the PDF/UA rules.
The long version, with the exact Markdown that produces each failure, is in Markdown Tables That Survive a PDF Page.
Diagrams arrive as pictures
Mermaid renders to an image before it reaches the page. That is fine for print, and it is the reason the text inside a diagram is not searchable and not read by a screen reader unless you give the image alternative text. Give every diagram its own paragraph (do not put it inline in a sentence), keep node labels short enough to survive a 40% width reduction, and write alt text that states the conclusion the diagram supports rather than its shapes.
Details and the label-length trick: Mermaid to PDF Without Screenshots.
Equations are a font question
A formula is only as portable as the fonts that render it. If a glyph is missing, the exporter substitutes something visually similar and the printed result silently changes meaning — a prime that reads as an apostrophe, an integral sign that becomes a box. Export one page containing every symbol you use, then read it on paper before submitting. Formula-heavy documents are also the case where switching the rendering engine is worth it, because the default engine is tuned for prose, not for display math.
How to check each glyph: Equations That Still Read on Paper.
The order to fix them
- Check the source first. The free check reports missing image alt text, skipped heading levels and empty links — the problems that are cheaper to fix in Markdown than in a PDF.
- Fix width before content. A table that is too wide will still be too wide after you reword a cell.
- Add structure the reviewer needs. Page numbers and a table of contents turn a wall of pages into something a supervisor can cite.
- Export, then read the PDF — not the preview. The preview is print-accurate for spacing, but only the exported file shows which fonts were embedded and whether a diagram became an image.
- Re-export with the accessibility profile if the destination requires it. That adds tagged structure and image alternative text to the file itself; the background is in what a tagged PDF is.
Start from a skeleton instead
Both downloadable skeletons already contain the front matter these fixes depend on: the report template and the thesis template. If you have a folder of documents rather than one, the batch page applies the same settings to all of them.
The same renderer is one click away. Open a working sample and export it before pasting your own Markdown.