Turning Markdown into a PDF on macOS

Sooner or later a Markdown file has to leave the world of Markdown. Someone wants it as an attachment, a client wants it on paper, or a process wants an artefact it can archive. Here are the routes that work on a Mac, and what each one does to the parts that are not plain text.

The hard parts are always the same three: diagrams, maths, and fonts. Anything can print a paragraph.

1. Print from an app that renders properly

The shortest path. Open the file in a viewer that draws the page correctly, press ⌘P, and in the print dialog choose Save as PDF from the PDF menu in the corner.

This works because macOS treats “print” and “make a PDF” as the same operation, which is one of the genuinely good decisions in the system. Whatever is on the page — a rendered Mermaid diagram, a KaTeX formula, a syntax-highlighted code block — goes into the PDF as vector text and shapes, not as a screenshot.

Two things to check in whatever app you use:

• Does it have a print stylesheet? A page designed for a screen printed straight onto A4 gives you a narrow column of text down the left of every sheet. A decent app switches to black on white, uses the full width, and avoids breaking a page in the middle of a code block.
• Do ticked task list boxes survive? Printers routinely drop form-control colours, which silently empties every checkbox. It is a small thing that makes a printed checklist useless.

Hem has a proper print stylesheet, including the checkbox detail above, and skips the dialog altogether: File → Export as PDF… asks only where to save. Most serious Markdown apps print well; it is worth a test print before you rely on one.

2. Export a self-contained HTML file

Sometimes PDF is the wrong artefact. A PDF of a wide table is a bad table, and a PDF of a document somebody needs to copy text out of is an act of hostility.

A single HTML file avoids both, but only if it is genuinely single. An “export to HTML” that produces a file plus a folder of assets, or a file that pulls a stylesheet off a CDN, is not something you can email — and it will look wrong the moment the recipient is offline or the CDN moves.

What a self-contained export needs to inline:

• the stylesheet,
• the maths fonts, as data URIs, if the document contains maths,
• local images referenced from the document,
• the rendered diagrams, as SVG.

Done properly, the result is one file you can attach, open anywhere, and read in ten years. Hem’s Export as HTML… produces one; a document with a page of KaTeX in it comes out around 400 kB, most of which is the maths fonts.

3. Pandoc, for anything repeatable

brew install pandoc
brew install --cask basictex        # for PDF via LaTeX

pandoc notes.md -o notes.pdf
pandoc notes.md -o notes.html --standalone --embed-resources

Pandoc is the right answer for a pipeline: a build step, a script, a hundred files, a house template. It handles citations, cross-references, numbered sections and a dozen output formats, and it is the only option here that will produce a genuinely typeset document.

The costs are real, though. A working PDF path means a TeX installation (BasicTeX is around 100 MB, MacTeX several gigabytes). Mermaid needs a filter and a headless browser. Maths works well; diagrams take configuration. For one file, once, it is a lot of setup.

For HTML output, note --embed-resources --standalone: without them you get the file-plus-folder problem from the previous section.

4. Print from a browser

If the Markdown is already rendered somewhere in a browser — a GitHub page, a docs site, a local preview — ⌘P and Save as PDF works the same way it does in a native app.

The output is at the mercy of the site’s print stylesheet, which is often an afterthought: navigation bars in the middle of the document, a sidebar taking a third of every page, links printed as bare text with no address. Safari’s Reader mode (⇧⌘R) sometimes rescues it by throwing the layout away first.

Fine in a hurry. Not something to build a process on.

5. Visual Studio Code, with an extension

The Markdown PDF extension adds an export command to the context menu and produces PDF, HTML, PNG or JPEG. It works by rendering in the bundled Chromium and printing that.

Convenient if VS Code is already open. Be aware that what it renders is VS Code’s preview, extensions and all, which is not necessarily what the file looks like anywhere else — and that the output depends on which preview plugins you happen to have installed.

Which to use

Route	Diagrams	Maths	Setup	Best for
⌘P in a Markdown app	Yes, if the app renders them	Yes	None	One document, right now
Self-contained HTML export	Yes	Yes	None	Sharing something readable and copyable
Pandoc	With a filter	Excellent	Substantial	Pipelines and typeset output
Print from a browser	Whatever the page shows	Same	None	The document is already on screen
VS Code extension	Depends on plugins	Depends	Small	You live in VS Code

For a single file on your Mac, the first two are almost always right, and the choice between them is really the choice between paper and screen. Use PDF when the layout is the point — a document that will be printed, signed or archived. Use HTML when the content is the point and the reader may want to copy a command out of it.

Two details that catch people out

Wide tables. A ten-column table does not fit on A4 and no renderer can fix that. Landscape orientation in the page setup buys you some; beyond that, the honest answer is that the table wants to be a spreadsheet or the PDF wants to be HTML.

Dark mode. If you print while your Mac is in dark mode, a naive app will hand the printer a black page. Every app mentioned here switches to a light print stylesheet, but a quick print preview costs nothing and a full ink cartridge costs rather more.

---

Hem exports a PDF with a proper print stylesheet, a single self-contained HTML file and a Word document, diagrams and maths included. Free, open source, 5.7 MB, macOS 14 and later.