Markdown to PDF in the browser: image PDF vs text PDF, page size, margins and page breaks

A Markdown file is not something you can send to a client, attach to a ticket or print. The usual path is a PDF or an image, and the choices that matter are made before you press Export: which kind of PDF, what page size, how wide the margin is, and what happens at the bottom of each page.

Two PDFs that look the same and behave differently

The Markdown viewer and exporter on this site offers two PDF formats. They are built differently, and each one fixes a different problem.

Use the image PDF for something a person will look at and pass on, such as a one-page report or a styled note, where matching the preview exactly matters. Use the text PDF for anything that has to be searched, copied from, read by a screen reader or run to many pages. The text PDF opens the print dialog: choose Save as PDF as the destination and turn off Headers and footers, otherwise the browser adds a date and URL to every page.

Page size and margin

Sizes are given in CSS pixels at 96 per inch. A4 is 794 × 1123 and US Letter is 816 × 1056. The fit-content sizes (800, 390, 768 and 1200 px wide) have no page height and give one long page, so they suit screens and messaging, and they are the wrong choice for printing: an image PDF made from one of them is a single tall page (600 pt wide for the 800 px size), not a stack of A4 sheets. Pick A4 or Letter for paper.

The page margin applies on every side, and the default is 40 px, which is about 1.06 cm. Printers often need more. One centimetre is about 38 px, so for a 2 cm margin enter 76. In the text PDF, the same value becomes the @page margin, so the setting you see in the preview is the one used for printing. If the print dialog has its own Margins setting, leave it on Default so that it does not override the page.

Page breaks

A fixed-height page cuts wherever the page ends unless something stops it, and the usual result is a line of text split across two pages or a heading stranded at the bottom. The option “Fixed-height pages: move images and text to the next page instead of cutting them” handles this. When it is on, a paragraph, list item, code block, image or table row that would straddle the boundary moves down to the next page, and a heading is kept together with what follows it. The preview draws a dashed line and a Page N label at each break, so you can check before exporting.

There are two limits. A block taller than a whole page, such as a very long code listing, cannot be kept intact and is split anyway. And there is no way to insert a manual page break: raw HTML in this tool is shown as text, so a <div style="page-break-after: always"> appears on the page as visible code instead of breaking it. Plan breaks by editing headings and section lengths, and look at the preview.

Raw HTML as text has a second consequence. A README that opens with a centred <p align="center"> logo block will print that markup literally. Convert it to a Markdown image or delete it before exporting.

Long documents and the pixel-density warning

The image PDF and the image formats render the whole document onto one canvas and slice it into pages, and a browser canvas has a size ceiling; this page caps its edge at 16,384 px. At 2× pixel density an A4 page is about 2,246 px tall, so more than about seven pages exceeds it, and at 1× the limit is about fourteen. When that happens the tool lowers the density and says so in the status line, for example “pixel density was lowered to 1.45×”, which makes a long document slightly softer. If a long document needs crisp text, switch to the text PDF, which has no such limit.

Density is a trade-off in its own right. At 2×, an A4 page has an effective resolution of 192 dpi, which is clear on screen and acceptable on a printer. Raising it to 3× or 4× grows the file and brings a long document closer to the canvas ceiling.

Chinese and other non-Latin text

Garbled or missing glyphs after exporting usually come from a tool that needs a font file for the language. Here the browser does the drawing, so the question is only whether your device has a font that covers the characters. The font stacks include PingFang SC, Microsoft YaHei and Noto Sans CJK SC for sans-serif, and Songti SC, SimSun and Noto Serif CJK SC for serif. On Windows, macOS and most desktop Linux systems with CJK fonts installed, Chinese renders correctly, and in the image PDF the text is baked into the picture, so the reader needs nothing installed. Empty boxes mean the device has no suitable font. In that case, install one such as Noto Sans CJK, rather than changing settings in the tool.

For comparison, pandoc with a LaTeX engine fails on Chinese until you give it a CJK font, for example --pdf-engine=xelatex -V CJKmainfont="Noto Serif CJK SC". That error is specific to that pipeline.

Images in the document

Local images are not read from your disk by path, because a web page cannot do that. Use Add images, Add image folder or paste a screenshot, and the tool matches the file name used in the Markdown. A folder that holds a Markdown file loads that as well. Images that cannot be matched appear as dashed labels, and the status line lists their names. Images linked from other sites are fetched and embedded, but only when the host allows cross-origin reads. Those that do not are replaced by a dashed label. Use a data: address or an image from a host that sends CORS headers.

Themes and paper

Dark themes export with their background, as the print mode forces background colours on. That looks good on screen and uses a lot of toner on paper. For printing choose Light, GitHub or Sepia, and keep the dark themes for PDFs that will only be read on a screen.

Export, copy and preview all run in the page, so the Markdown is not uploaded.

Open the tool: Markdown Viewer & Exporter

Back to guides