How to Convert Markdown to PDF
Convert a Markdown file to PDF with Pandoc, choose a PDF engine, and solve common layout, font, and dependency problems.
Use Pandoc for a repeatable command-line conversion:
pandoc input.md -s -o output.pdfThe default PDF route uses LaTeX, so Pandoc alone may not be enough: install a suitable LaTeX engine too. Pandoc also supports other PDF engines and intermediate formats. Choose based on the dependencies you can install, the styling control you need, and the fonts and content your document uses. See the official Pandoc getting-started guide and User’s Guide.
1. Choose a conversion route
| Route | Good fit | What to account for |
|---|---|---|
| Pandoc with LaTeX | Repeatable command-line conversion and documents suited to a typesetting workflow. | Install Pandoc and a LaTeX engine. The engine must be available to the command. |
| Pandoc with another PDF engine or intermediate format | You already use another supported engine, or want HTML and CSS to control the output style. | Install and configure that engine and its dependencies. Pandoc supports PDF generation through LaTeX, ConTeXt, roff ms, or HTML intermediates. |
| Browser-based Pandoc WebAssembly | A browser workflow is preferable to installing a local command-line tool. | Pandoc documents a WebAssembly option that runs in the browser after its code is downloaded. Check the selected browser tool’s PDF support and privacy details; do not assume every online converter runs locally. |
Pandoc is a command-line converter, not a graphical editor. The standard workflow is to install Pandoc, open a terminal in the directory with the Markdown file, then run the conversion command.
2. Install dependencies and convert a file
- Install Pandoc using the official installation instructions for your platform.
- Install a PDF engine. Pandoc’s getting-started guide gives MacTeX for macOS, MiKTeX for Windows, and TeX Live for Linux as examples. Check current installation guidance and choose the package appropriate for your system.
- In a terminal, change to the directory containing the input file, or provide full paths.
- Run the command and inspect the generated PDF.
pandoc input.md -s -o output.pdfFor example, with a file named README.md:
pandoc README.md -s -o README.pdf-s asks Pandoc to produce a standalone document. Pandoc commonly infers input and output formats from filenames, so the .md and .pdf extensions are enough for this basic case. If you use standard input, an unusual extension, or a specific Markdown variant, specify the format explicitly with -f and -t.
# Explicit input and output formats
pandoc -f markdown -t pdf input.md -o output.pdf
# Read Markdown from standard input
cat input.md | pandoc -f markdown -s -o output.pdf3. Configure the PDF engine and layout
Use --pdf-engine to select the program that creates the PDF. That program must be installed and available on your PATH. The exact arguments and capabilities depend on the selected engine.
# Select a LaTeX engine
pandoc input.md -s --pdf-engine=xelatex -o output.pdf
# Set one-inch margins on LaTeX output
pandoc input.md -s -V geometry:margin=1in -o output.pdf
# Set different margins on LaTeX output
pandoc input.md -s -V geometry:top=1in -V geometry:bottom=1in \
-V geometry:left=1.25in -V geometry:right=1.25in -o output.pdfThe margin variables shown are for LaTeX output; do not assume they apply unchanged to every engine. For finer layout control, choose an engine and its configuration deliberately. Pandoc supports HTML as an intermediate format, where CSS can style the document.
# Use HTML as the intermediate format, with CSS for styling
pandoc input.md -s -t html --pdf-engine=ENGINE \
-c print.css -o output.pdfReplace ENGINE with an installed engine that supports the chosen route. Confirm that the engine accepts the options you need, then review the result for page breaks, long tables, wrapping, and embedded images. Those are document-specific layout checks, not properties guaranteed by a particular engine.
4. Handle images, links, and special content
- Images: Keep referenced image files at paths Pandoc can resolve from the conversion directory, or use appropriate resource-path options. Check that images appear in the output and fit the page.
- Unicode and non-Latin scripts: Missing glyphs often point to the engine or font. Pandoc’s FAQ documents that default
pdflatexdoes not handle Chinese characters and recommends XeLaTeX with a font containing the needed glyphs. For other scripts, check the chosen engine and font rather than assuming the same remedy applies universally. - Markdown extensions: If the source relies on tables, footnotes, math, or other Markdown features, confirm that the selected input format enables the syntax you use. Pandoc supports multiple Markdown variants.
- Page layout: Long code blocks, wide tables, and large images may need source edits or engine-specific styling. Inspect the actual pages at the intended print size.
- Metadata: If you need document metadata or a title block, use Pandoc metadata in the Markdown or a metadata file and verify how the selected output route renders it.
5. Troubleshoot conversion failures
| Symptom | Likely cause | Fix |
|---|---|---|
| PDF creation fails with a missing executable or engine error. | Pandoc is installed, but the default LaTeX engine or selected PDF engine is not. | Install the required engine and ensure its executable is available on PATH, or select an installed supported engine with --pdf-engine. |
| Chinese characters are missing or conversion reports font problems. | The default pdflatex route does not handle Chinese characters, or the selected font lacks the required glyphs. |
For Chinese, follow the documented Pandoc FAQ route: use XeLaTeX and choose a font containing the characters. For other scripts, verify engine and font coverage. |
| Margins do not change. | The geometry variables are being used with a non-LaTeX route or are otherwise not recognized by the selected engine. |
Use the documented geometry variables with LaTeX output, or configure margins through the chosen engine’s or HTML/CSS route’s own mechanism. |
| Images are absent. | The resource path is wrong, the file is unavailable from the conversion environment, or the chosen route cannot access it. | Check relative paths from the working directory, provide resources in the expected location, and inspect the intermediate output if needed. |
| Output styling differs from the source or desired print layout. | The selected engine has different styling behavior, or no stylesheet/configuration was applied. | Choose the route intentionally, configure CSS for HTML intermediates where appropriate, and inspect the resulting PDF page by page. |
| The error is hard to diagnose. | The generated intermediate markup may reveal what Pandoc is passing to the PDF stage. | Write an intermediate LaTeX file and inspect it: pandoc input.md -s -o debug.tex. This is the troubleshooting approach recommended in the Pandoc User’s Guide. |
6. Automate conversion
For scripts and build jobs, pass explicit paths, check the command’s exit status, and keep the PDF engine installed in the same environment as Pandoc. A shell function can make a one-file conversion repeatable:
#!/usr/bin/env sh
set -eu
input=${1:?Usage: md-to-pdf input.md [output.pdf]}
output=${2:-"${input%.*}.pdf"}
pandoc "$input" -s -o "$output"
printf 'Created %s\n' "$output"Save it as md-to-pdf, make it executable with chmod +x md-to-pdf, then run ./md-to-pdf notes.md. For CI, install both Pandoc and the selected PDF engine in the job image; pinning your environment is useful when consistent output matters. Conversion time and output quality depend on the document, engine, and environment; the cited Pandoc documentation provides no universal speed or quality benchmark. Local CLI conversion has no per-conversion service charge, though engines and their dependencies require installation and maintenance.
Or skip the browser setup
If the PDF workflow also needs a screenshot of a rendered web page, ScreenshotNeo can return an image or PDF from one API request. It is a website screenshot API and MCP server; it does not convert a Markdown file directly. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Sign up for 1,000 free screenshots a month, with no card.
Frequently asked questions
Can I convert Markdown to PDF without LaTeX?
Yes. Pandoc supports other PDF engines and intermediate formats. Choose one whose dependencies you can install; HTML intermediates can be styled with CSS.
Does Pandoc convert Markdown to PDF in the browser?
Pandoc documents a WebAssembly browser option. Check the selected interface’s PDF route and limitations before relying on it; local command-line Pandoc with an installed engine is the direct documented command-line workflow.
How do I make the same PDF on different machines?
Use the same Pandoc version, PDF engine, fonts, and relevant configuration on each machine, and review output after environment changes. The documentation describes available routes but does not promise byte-for-byte identical output across setups.
Can Pandoc create PDFs from formats other than Markdown?
Yes. Pandoc is a general document converter with multiple input formats. Specify the input format with -f when it cannot be inferred reliably.
Sources
- Pandoc: Getting started — basic conversion command and setup.
- Pandoc User’s Guide — PDF engines, intermediate formats, CSS, and debugging.
- Pandoc FAQs — margins, font/script guidance, and alternative routes.
- Installing Pandoc — current installation instructions.
- Pandoc releases — project release information for the WebAssembly option.
