Markdown to PDF on a Mac
Markdown is easy to write, but sometimes you need to send a file to someone who just wants a PDF. A Mac has a PDF printer built in, so you do not need to buy anything. This page shows three free ways to make a PDF from Markdown, and how to keep images, code blocks and diagrams in the result.
Way 1: print to PDF from a viewer or browser
This is the fastest way for one file.
- Open the Markdown file in an app that shows it formatted. This can be a Markdown viewer, an editor preview, or a browser page that renders Markdown, such as the file view on GitHub.
- Choose File ▸ Print, or press ⌘P.
- In the print dialog, open the PDF menu and choose Save as PDF.
- Pick a name and location, and click Save.
The PDF looks like what the app shows, adjusted for paper. Check the preview in the print dialog before saving. Wide tables and long code lines may be cut off or wrapped.
In a browser, look for options like “Background graphics” in the print dialog. Without them, coloured code blocks may print without their background. You can also turn off headers and footers there, which removes the page URL and date from the PDF.
Way 2: pandoc on the command line
pandoc is a free, open-source document converter. It is a good fit when you convert files often, or want the same layout every time.
Install it, for example with Homebrew:
brew install pandocThen convert a file:
pandoc notes.md -o notes.pdfBy default, pandoc makes PDFs with LaTeX. If you do not have a LaTeX engine installed, the command fails with a message about it. You have two choices: install a LaTeX distribution, or use another engine. For example, pandoc can use an HTML-based engine if one is installed:
pandoc notes.md -o notes.pdf --pdf-engine=weasyprintpandoc has many options for fonts, margins, a table of contents and templates. Its manual at pandoc.org lists them all.
Way 3: a VS Code extension
If you already write in Visual Studio Code, an extension can export the file you are editing. Search the Extensions view for “Markdown PDF”. Extensions like this add a command to the Command Palette that saves the current file as PDF, and often HTML or images as well.
Read the extension’s description before you install it. Check which Markdown features it supports, and whether it renders Mermaid. Some extensions download a browser engine the first time you export.
Keep images in the PDF
Missing images are the most common problem. Markdown files link to images, usually with a relative path like . The PDF tool has to find that file.
- Keep images next to the Markdown file, or in a folder below it.
- With pandoc, run the command from the folder of the Markdown file. Or add
--resource-pathwith the folder that holds the images. - Images from the web need an internet connection while you convert. If you need the PDF offline, download them and link the local copies.
- Very large images may run off the page. Most tools scale them, but check the result.
Keep diagrams in the PDF
Mermaid diagrams are text in a code block. They only become pictures when a tool renders them. If the PDF shows the Mermaid code instead of a diagram, the tool did not render it.
You have three options:
- Print from an app that already shows the diagrams, as in Way 1. What you see is what goes into the PDF.
- Turn diagrams into image files first with the Mermaid command line tool, mermaid-cli, then link those images in the Markdown.
- With pandoc, use a filter that renders Mermaid during conversion. There are community filters for this. Each one needs its own setup.
Math works the same way. If your file uses LaTeX math, check that the tool renders it. pandoc handles math well through LaTeX.
Which way to pick
- One file, right now: print to PDF from a viewer or browser.
- Many files, the same style each time: pandoc.
- You live in VS Code anyway: an extension.
Always open the PDF and scroll through it once. Look at images, tables, code blocks and diagrams.
Markko
Markko is a read-only Markdown viewer for macOS. The free version can print, so you can use Save as PDF from its print dialog. Markko Pro adds export to PDF and HTML, and renders Mermaid diagrams and math with KaTeX.
FAQ
Why are images missing in my PDF?
Images are usually linked with relative paths. If the tool runs from another folder, it cannot find them. Run it from the folder of the Markdown file, or tell it where to look, for example with pandoc's --resource-path option.
Why do Mermaid diagrams show up as code in the PDF?
The tool that made the PDF does not render Mermaid. Use a tool that draws the diagrams first, or turn them into images before you convert.
Does pandoc need anything else to make PDFs?
By default, yes. pandoc uses a LaTeX engine to create PDFs. You can install one, or tell pandoc to use a different PDF engine with --pdf-engine.
Can I keep links clickable in the PDF?
Usually yes. Save as PDF from the macOS print dialog and pandoc both keep links in most cases. Check the result, since it depends on the app.