How to Convert Markdown (MD) to PDF for Publishing
Why Markdown Writers Need PDF Output
Markdown is the format of choice for technical writers, developers, and bloggers who want to focus on content without fighting a word processor. Files stay small, version control works cleanly, and the syntax is readable even in raw form. The problem appears the moment you need to hand something to a client, submit a report, or publish a polished document. Plain .md files render differently in every editor, and most non-technical recipients have no idea how to open them. PDF solves that problem. A PDF renders identically on every device, embeds fonts, preserves your heading hierarchy, and can be printed without reformatting surprises. A 40-page technical spec that looks perfect in VS Code can arrive at a client's inbox as a single, self-contained file they can open in any browser or PDF reader without installing anything. The conversion process is not always trivial, though. Markdown itself has no standard for page breaks, margins, or font sizes — those decisions belong to whatever renderer processes it. That gap between 'text with asterisks' and 'print-ready PDF' is exactly what this guide covers, including where tools like CocoConvert fit and where you might need something more specialized.
What Happens During MD-to-PDF Conversion
Understanding the pipeline helps you predict and fix output problems. Converting Markdown to PDF is actually a two-step process under the hood, even when a tool hides both steps behind a single button. Step one: the Markdown is parsed into an intermediate format — almost always HTML. Every heading becomes an `<h1>` through `<h6>` tag, bold text becomes `<strong>`, code blocks become `<pre><code>` elements, and so on. The quality of this step depends on which Markdown flavor the parser supports. CommonMark is the most standardized spec. GitHub Flavored Markdown (GFM) adds tables, task lists, and strikethrough. If your document uses GFM features like pipe tables and the converter only handles CommonMark, those tables will appear as raw pipe characters in the output. Step two: the HTML is rendered to PDF using a headless browser engine (Chromium-based tools like Puppeteer) or a dedicated PDF library. This step applies CSS for typography, spacing, and page layout. Margins are typically set around 20–25mm on each side for A4 or letter paper. Code blocks get a monospace font. If the tool uses a sensible default stylesheet, the result looks professional without any configuration. The practical implication: if your PDF output looks wrong, the bug is usually in one of these two steps — either the Markdown wasn't parsed correctly, or the CSS applied during rendering produced unexpected spacing or font choices.
Using CocoConvert for Quick MD-to-PDF Conversions
For straightforward documents — README files, meeting notes, short reports, documentation pages — CocoConvert's [MD-to-PDF converter](/convert/md-to-pdf) handles the job without requiring any software installation or command-line knowledge. The process is three steps. First, upload your .md file by dragging it onto the converter or clicking the file picker. Files up to 25 MB are supported, which covers the vast majority of Markdown documents (a 10,000-word document with no embedded images is typically under 100 KB). Second, click Convert. The tool parses CommonMark and GFM syntax, including fenced code blocks with language hints, pipe tables, and inline HTML. Third, download the resulting PDF. Default output uses A4 page size with 20mm margins, a readable sans-serif body font at 11pt, and syntax highlighting in code blocks. Headings scale from 24pt (H1) down to 13pt (H6). These defaults work well for most documentation and reports. Be honest about the limitations here: CocoConvert does not currently support custom CSS injection, YAML front matter processing, or LaTeX math notation (e.g., `$E = mc^2$` will appear as literal text rather than a rendered equation). If your document contains mathematical formulas, you will get better results from Pandoc with a LaTeX backend or from tools like MathJax-enabled converters. Similarly, if you need precise control over page breaks — forcing a new page before each H2, for example — a command-line workflow gives you more control.
Preparing Your Markdown File Before Converting
A few minutes of preparation before conversion prevents the most common output problems. **Check your heading structure.** A document with multiple H1 headings will produce a PDF where several lines share the same large font size, which looks unstructured. Use a single H1 for the document title, H2 for major sections, and H3 for subsections. Most Markdown linters (markdownlint rule MD025) flag multiple H1s automatically. **Handle images carefully.** If your .md file references images with relative paths like ``, those paths will break when the file is uploaded alone to a web-based converter. Either embed images as Base64 data URIs directly in the Markdown, or use absolute URLs pointing to publicly accessible images (e.g., ``). For a document with 5–10 images, converting to Base64 manually is tedious — consider zipping the .md file with its image folder if your converter supports archive uploads, or use a local tool like Pandoc for image-heavy documents. **Remove or replace unsupported syntax.** If your file uses Hugo shortcodes, Obsidian callouts (`> [!NOTE]`), or other non-standard extensions, strip them or convert them to standard Markdown equivalents before uploading. An Obsidian callout can be replaced with a simple blockquote; a Hugo `{{< figure >}}` tag can be replaced with a standard `![]()` image reference. **Check line endings.** Windows-style CRLF line endings occasionally cause paragraph spacing issues in some parsers. Running the file through a quick `dos2unix` conversion, or saving with LF endings from your editor, eliminates this variable.
When to Use Pandoc Instead (or Alongside CocoConvert)
Pandoc is a free, open-source command-line tool that handles Markdown-to-PDF conversion with far more configurability than any web tool. Knowing when to reach for it saves time. Install Pandoc and a LaTeX distribution (TeX Live on Linux/Mac, MiKTeX on Windows), then run: ``` pandoc report.md -o report.pdf --pdf-engine=xelatex -V geometry:margin=1in -V fontsize=12pt ``` This single command converts `report.md` to a PDF with 1-inch margins and 12pt body text. Adding `--toc` generates a table of contents automatically. The `-V` flag passes variables to the LaTeX template — you can set `mainfont`, `monofont`, `papersize`, `linestretch`, and dozens of other parameters. For math-heavy documents, Pandoc with XeLaTeX is the right tool — it renders LaTeX equations natively. For documents requiring a custom cover page, running headers and footers, or precise widow/orphan control, a LaTeX template gives you full typographic control. The tradeoff is setup time. Installing TeX Live takes 3–5 GB of disk space and 15–30 minutes. Debugging LaTeX template errors requires familiarity with LaTeX syntax. For a one-off README conversion at 11 PM before a deadline, CocoConvert is the faster path. For a 200-page technical manual that will be published quarterly, investing in a Pandoc + LaTeX workflow pays off after the second or third edition. These tools are not mutually exclusive. A reasonable workflow: use CocoConvert for quick previews and sharing drafts, then run the final version through Pandoc with a polished template for the published output.
Troubleshooting Common Conversion Problems
**Tables appear as plain text.** This usually means the converter is using a CommonMark-only parser that doesn't support GFM pipe tables. Verify that your table syntax is correct — every row needs the same number of pipe characters, and the separator row (the one with dashes) must be present. If the converter supports GFM, a correctly formatted table will render; if it doesn't, switch to a tool that does, or convert the table to an HTML `<table>` block, which most Markdown parsers pass through unchanged. **Code blocks lose indentation.** This is a font issue — the PDF renderer fell back to a proportional font for code. Check whether the converter applies a monospace font to `<pre>` elements. If you're using Pandoc, add `--variable monofont='Courier New'` to force a specific monospace font. **Images are missing.** Almost always a path resolution problem. See the preparation section above. Confirm that image URLs return HTTP 200 and are not behind authentication. **The PDF has no page numbers.** Web-based converters typically don't add running headers or footers because doing so requires CSS `@page` rules with counter support, which not all PDF engines handle consistently. If you need page numbers, Pandoc with a LaTeX backend adds them by default, or you can post-process the PDF in Adobe Acrobat (Tools > Edit PDF > Header & Footer > Add). **Long lines in code blocks overflow the page margin.** This is a line-wrapping issue. In CSS, `pre { white-space: pre-wrap; }` fixes it, but you can't inject CSS in most web converters. The workaround is to manually wrap long lines in your source file before converting, keeping lines under 80–90 characters.
Choosing the Right Settings for Publishing
The word 'publishing' covers a wide range of outputs, and the right settings differ significantly between them. **For web or email distribution:** A4 or US Letter page size, 20–25mm margins, 11–12pt body text. Embed all fonts to ensure consistent rendering on recipient machines. If file size matters — say, you're attaching to an email with a 10 MB limit — avoid embedding large image files at full resolution. Resize images to 150–200 DPI before including them in the Markdown source. **For print:** Use at least 300 DPI for any raster images. Margins should be wider — 25–30mm — to account for binding if the document will be stapled or bound. If printing through a professional service, ask whether they require PDF/X-1a or PDF/X-4 compliance; most web converters produce standard PDF 1.4 or 1.5, not print-production PDF/X variants. **For e-readers and tablets:** Consider whether PDF is actually the right format. EPUB handles reflowable text better on small screens. That said, if PDF is required, a smaller page size (roughly 6×9 inches, similar to a trade paperback) produces a better reading experience on a tablet than an A4 page scaled down. **For technical documentation portals:** Many documentation platforms (ReadTheDocs, GitBook, Docusaurus) have their own PDF export pipelines built on Chromium or WeasyPrint. If you're already using one of those platforms, their native export will respect your site's theme and navigation structure better than converting individual .md files separately. For most everyday publishing needs — sharing a polished report, distributing a spec document, or archiving a README — converting directly through [CocoConvert's MD-to-PDF tool](/convert/md-to-pdf) with default settings produces a clean, readable result in under a minute.