3 min readConversions
Draft in Markdown and get a clean paginated PDF out
Why Markdown suits documents that change often, which elements survive into a paginated PDF, and how to handle page breaks, tables, and code in the output.
The short answer
Write the document in Markdown, watch the paginated preview update as you type, and export a searchable PDF. Because the source is plain text, it diffs cleanly in version control, contains no hidden formatting state, and produces the same output every time it is rendered.
- Plain text sources diff cleanly and carry no hidden formatting state, which makes reviewed documents far easier to maintain.
- Pagination is the hard part of the conversion; check where tables, code blocks, and headings break.
- Markdown deliberately has no layout control, so use it for structured text rather than designed pages.
Markdown is the right format for a surprisingly large share of documents: notes, specifications, reports, runbooks, meeting records, and anything that will be revised repeatedly by more than one person. Getting a professional PDF out of it should not require a detour through a word processor.
Why write in Markdown at all
The advantages are structural rather than aesthetic.
- It diffs. A plain text file shows exactly what changed between two versions, line by line. A binary word processor document does not, which is why review comments on them tend to be "I changed a few things".
- There is no hidden state. No inherited styles from a paragraph you deleted, no invisible formatting carried in from a paste, no character that is mysteriously a different font.
- It is stable. The same source produces the same output today and in five years, on any machine.
- It keeps you writing. There is no formatting to fiddle with, so the time goes into the words.
- It converts to anything. The same source becomes a PDF, a web page, or a slide deck.
The Markdown tool pairs the source with a paginated preview, so you see the page breaks while you write rather than discovering them at export.
What translates cleanly
Standard Markdown structures map directly onto document elements:
| Markdown | In the PDF |
|---|---|
# through ###### |
Heading hierarchy |
**bold**, *italic* |
Bold and italic text |
- and 1. lists |
Bulleted and numbered lists, including nesting |
> quote |
Indented block quote |
| Fenced code blocks | Monospaced blocks |
| Pipe tables | Ruled tables |
[text](link) |
Working links |
--- |
Horizontal rule |
That covers nearly everything a structured text document needs. Headings are the part worth being disciplined about: use them in order, without skipping levels, because they define the document's outline and, in an accessible PDF, its navigation structure.
Pagination is the part that needs attention
Markdown has no concept of a page. HTML, its usual output, scrolls forever. A PDF does not, and the conversion has to decide where every page ends.
Check the preview for the usual problems:
- Orphaned headings. A section title alone at the foot of a page, with its content overleaf.
- Split tables. A table broken across pages without repeating its header row becomes hard to read.
- Split code blocks. Less serious, but a listing broken mid-function is awkward.
- Stranded list items. One bullet marooned at the top of a page.
- Wide content overflowing. Long lines of code and wide tables do not wrap the way prose does, and they run off the right margin.
Wide tables are the most common real problem. A table with eight columns of numbers fits a browser window and does not fit an A4 page. Reduce the columns, abbreviate the headers, or accept a landscape section.
Images and links
Images sit where you put them and are sized to fit the text column. Two habits help: use images at roughly the resolution they will be displayed, since a 12-megapixel photograph on a half-page figure inflates the PDF enormously; and always write meaningful alternative text, which carries into the PDF's accessibility information.
Links remain clickable in the export. Remember that a printed document cannot be clicked, so if the document will be read on paper, spell out important URLs in the text rather than hiding them behind "click here".
When another tool fits better
Markdown is intentionally limited. It gives you structure, not layout. If you need multi-column pages, precise positioning, text wrapping around images, sidebars, or a designed cover, Markdown will frustrate you.
- For a rich document written directly with formatting control, use the document creation tool.
- For full control over layout using stylesheets, author in HTML and use the HTML conversion tool.
- If you are starting from an existing PDF and want editable text back, that is the opposite direction — see the conversion guide for how much structure realistically survives that trip.
Because rendering happens in this browser workflow, the draft content is processed on your device. For specifications, internal reports, and anything written before it is ready to be seen, that is worth more than it sounds.
Tools used in this guide
Each workspace runs in this browser tab. Open one directly to apply the steps above to your own document.
Written by The PdfEditorOnlineFree team. Published and last reviewed . Product behaviour described here reflects the linked workspaces at the time of review; check the tool page for current limits.