Markdown to PDF, typeset properly
Markdown was designed to be readable as plain text. A PDF is meant to arrive exactly as it was set. Most converters lose the second promise on the way: they render your Markdown as a webpage, then print the webpage. This page explains why that output looks the way it does, and what typeset output looks like instead.
Why most Markdown-to-PDF output looks wrong
The overwhelming majority of converters (the online tools, the editor export buttons, the npm packages) share one architecture: render HTML, print it. Browsers are superb at scrolling and terrible at pages, so the symptoms are always the same:
- Lines wrapped greedily, one at a time, leaving rivers of uneven spacing.
- A table sliced mid-row at the page break, its header lost on the next page.
- Code blocks overflowing the page edge, or shrunk to an unreadable size.
- A heading stranded at the bottom of a page; a paragraph's last line stranded alone at the top of the next.
- No hyphenation, so justified text gapes and ragged text zigzags.
None of this is a bug in any one tool. It is what printing a webpage is.
What typeset output looks like
A typesetting engine works the opposite way: it considers the paragraph as a whole and chooses the set of line breaks that reads best, the way books have been set for centuries. Concretely, in legivel's output:
- Paragraphs with even spacing, hyphenated where the language allows it, no loose lines.
- Tables that keep alignment and repeat their headers on every page they span.
- Code that highlights in your language and never leaves the page.
- Headings that stay with their text; no widows, no orphans.
- Mermaid diagrams and TeX math as vectors: crisp at any zoom, never a screenshot.
- A real document skeleton: table of contents with page numbers, sidebar bookmarks, internal links that jump, metadata from your front matter.
Sample: report PDF Sample: math PDF Sample: diagrams PDF
Your options today
| Route | Good for | The trade |
|---|---|---|
| Online converter tools | One file, right now, free | Browser-print output; your document uploaded to someone's server |
| Editor export | Notes, drafts | Same browser-print engine underneath |
| Command-line typesetting toolchains | Real typographic quality | A multi-gigabyte toolchain to install, version, and maintain |
| Browser-automation APIs | HTML you already have | A headless browser per request: slow, heavy, and still webpage pagination |
| legivel | Typeset quality at API speed and volume | In private beta: request access below |
Convert Markdown to PDF from your code
curl -X POST https://api.legivel.com/v1/render \
-H "content-type: text/markdown" \
--data-binary @report.md \
-o report.pdfPer-document options (themes, feature toggles, light or dark) travel as JSON:
curl -X POST https://api.legivel.com/v1/render \
-H "content-type: application/json" \
-d '{"markdown": "# Quarterly report\n…", "features": {"theme": "dark"}}' \
-o report.pdfFor AI workflows there is a native MCP server: your agents write Markdown, legivel makes it a finished document.
Frequently asked
What is the easiest way to convert Markdown to PDF?
For a single file, any online converter will do, and the result will look like a printed webpage. If the document matters (it goes to a client, a regulator, a customer), the easiest way that also looks right is an API call to a typesetting engine.
Is a free command-line toolchain the best converter?
A command-line typesetting toolchain produces genuinely typeset output, and it is free. The cost is the toolchain: a multi-gigabyte install, template debugging, and version drift across machines and CI. legivel exists to give that class of output as a single HTTP call.
Why does my Markdown PDF look bad?
Almost always because it was printed from a browser: greedy line wrapping, no hyphenation, CSS pagination. See the symptom list above.
Can I control page breaks?
You should not have to. The engine keeps headings with their text, repeats table headers, and avoids widows and orphans by construction.
Do tables and code blocks survive?
Tables keep alignment and repeat headers across pages. Code keeps its highlighting and wraps instead of overflowing.
Does Mermaid work? Does math work?
Thirty-two Mermaid diagram kinds and TeX math, all as vectors. Large diagrams get their own correctly sized page.
What about my images?
Images embedded in the document always render. Images linked from the web load too, for signed-in accounts, over a secure connection, and are never stored. Your document and the PDF leave our server the moment the PDF is delivered.
Can I convert Markdown to PDF by API?
Yes, that is what legivel is: REST for every document, MCP for AI agents.
legivel is in private beta.
Be first in line: tell us what you would generate.