the pdf came out with the hashes still in it

converting markdown to pdf with what macOS already has

start with what does not work, because it is the first thing everyone tries. macOS knows the file type — Spotlight tags a .md as net.daringfireball.markdown — and hands it to the plain-text preview anyway. Quick Look shows the raw source, TextEdit opens it, and File → Print → Save as PDF prints it in Helvetica with every # and asterisk where you typed it. textutil and cupsfilter on the command line do the same, in Monaco.

it is the same plain-text trap that catches Word files on the command line — textutil keeps the words and drops the document: convert Word documents to pdf in batch

the Shortcuts action that renders markdown

the one renderer Apple does ship is inside Shortcuts, as an action called Make Rich Text from Markdown. it turns the markdown into rich text, and a second action, Make PDF, turns that into a file. the shortcut you build is three steps:

1. open Shortcuts, make a new shortcut, and add Receive Files as input — or Get File if you would rather pick the file each time.
2. add Make Rich Text from Markdown, with the file as its input.
3. add Make PDF, then Save File, and run it from the share menu or the Finder Quick Actions list.

the action is Apple's own, and its behaviour on the Mac was last changed in macOS 13.4: Apple, What's new in Shortcuts

the cost is that you get rich text: headings, bold, lists, links — what a word processor thinks a document is. people who run anything longer than an email through it report the blank lines between paragraphs vanishing, and fix that with a Replace Text step before the conversion. a real route for notes, and built in. not a typesetter.

pandoc: md to pdf on Mac, free, and where the command stops

pandoc is not part of macOS, but it is free, open, and the tool every second search result points at, so it belongs here under its own name. it converts markdown into more or less anything, properly — headings, tables, code blocks, footnotes. Homebrew installs it, or the project's own page does.

why pandoc says pdflatex not found

the command everyone posts is pandoc notes.md -o notes.pdf. on a Mac with pandoc and nothing else, it does not produce a pdf. it stops with «pdflatex not found. Please select a different --pdf-engine or install pdflatex». pandoc does not draw pages itself: for a pdf it hands the document to a typesetting engine, and by default that engine is LaTeX, which is a separate install measured in gigabytes. the manual lists thirteen engines it can use, and none of them ships with macOS.

the engine list, and the line about LaTeX being required by default: pandoc manual, creating a PDF

the same shape on the video side, where the free tool is real and the price is knowing what to type: convert mov to mp4

the two pandoc routes that work without installing an engine

both use an app already on the Mac as the renderer, and both are per-file with a click in the middle:

1. through Safari: pandoc -s notes.md -o notes.html, open the html in Safari, File → Export as PDF. the -s matters — without it the html has no head and Safari renders it in the default serif.
2. through Pages: pandoc notes.md -o notes.docx, open it in Pages, File → Export To → PDF. tables come across as tables — the docx pandoc writes carries them, and Pages lays them out.

Export as PDF is a menu item in Safari, separate from the Print dialog, and it saves the whole page rather than the visible part: Apple, Safari User Guide

so for one file: Shortcuts if the document is simple, pandoc plus Safari or Pages if it has tables and code. both are free, both work, and both are a chain you have to know. the simple case ends at the second file, or the first time you forget which of the pandoc commands is the one that runs.

the chain gets shorter when the converter takes documents alongside images and video: the file converter

so what actually lays out a markdown file

on a Mac with nothing installed, build the Shortcuts action once. on a Mac with pandoc, use pandoc — through Safari or Pages, never straight to pdf. for a folder of markdown, or a file you want laid out without opening a second app, use a converter that reads markdown and writes the pdf itself — because every free route above ends in a click per file, the renderer being a browser or a word processor rather than the converter.

the pdf you get from any of these will embed fonts, and a long document can come out heavier than expected: compress a pdf on Mac

how hop converts markdown to pdf

hop's converter takes a .md file the way it takes a heic or a mov: drop it, or a folder of them, and the pdf lands beside the original as a copy. the layout is done by hop itself — no pandoc, no LaTeX, no browser in the middle, and nothing to download. it is native and runs offline.

• markdown goes to pdf, laid out by hop. Word files — .docx, .doc, .rtf — go to pdf or to markdown the same way.
• the other direction works too: the text of a pdf comes out as markdown, and a scanned page is read with Apple's Vision instead of coming back empty.
• a folder is one drop. there is no per-file step, because the renderer is the converter.
• originals are untouched; results are copies next to them.

the Vision part is its own tool, and it is what makes the scanned page in a pdf come back as text: text recognition

the last row is the boundary. a converter lays out what the markdown says; a document with a designed cover, running headers and a house font is a template job, and the tool for that is pandoc with a template or the app the layout was made in. hop is for the file, or the forty files, that need to be a readable pdf now.

when the pdf comes out wrong

• the hashes and asterisks are in the pdf. you printed the file from TextEdit, Quick Look or the Print dialog, and none of them renders markdown. the pdf is a printout of the source. go through the Shortcuts action or pandoc.
• pandoc says pdflatex not found. it is asking for a typesetting engine that is not on your Mac. write html or docx instead and let Safari or Pages produce the pdf.
• the paragraphs ran together. the Shortcuts route: rich text drops the blank lines markdown uses as paragraph breaks. a Replace Text step that doubles the line breaks before Make Rich Text from Markdown is the fix people use.
• the table is a column of words. the renderer did not read the table syntax. pandoc reads pipe tables; with the Shortcuts action, tables are the first thing to check in the output.
• the fonts are the browser default. you went through Safari without the -s flag, so the html had no styling. add -s, or pass your own css with --css.
• the images are missing. relative image paths resolve from where the renderer runs, not from where the file is. open the html from the same folder, or use absolute paths.
• the code block lost its indentation. the Shortcuts route again — rich text has no monospaced block. pandoc keeps code as code.
• the pdf is huge for a text file. embedded fonts, often one copy per heading style. it compresses well.

the same file-at-a-time shape, on the image side, where macOS does have a batch answer hidden in a right-click menu: convert heic to jpg

frequently asked questions

can i convert markdown to pdf on a Mac without installing anything?

yes, through Shortcuts: Make Rich Text from Markdown followed by Make PDF. it is Apple's own action and it renders headings, emphasis, lists and links. it produces rich text rather than a typeset page, so check tables and code blocks in the result before trusting it for anything long.

why does my markdown pdf still show the # symbols?

because the app that printed it does not render markdown. TextEdit, Quick Look and the Print dialog treat .md as plain text — macOS knows the file type and still previews it as text. the pdf is a printout of the source, not a rendering of it.

why does pandoc say pdflatex not found?

pandoc does not draw pages itself; for pdf it calls a typesetting engine, and the default is LaTeX, which is not installed on a Mac. either install an engine, or have pandoc write html or docx and export the pdf from Safari or Pages.

does Quick Look render markdown on Mac?

no. it shows the raw source. the file is typed as markdown, but the generator that draws it is the plain-text one. the rendered Quick Look previews people mention come from third-party extensions, not from macOS.

can i batch convert a folder of markdown files to pdf?

with pandoc, only halfway: a shell loop writes an html or docx per file, and the pdf still has to be exported from Safari or Pages one at a time. a converter that reads markdown and writes the pdf itself takes the folder in one drop.

does hop keep tables and code blocks?

hop lays out the markdown itself, with no browser or office app in the chain. what it does not do is templates: a designed cover, running headers and a house font are a pandoc-with-a-template job, and hop does not replace that.

the tool behind this

done with convert and compress

other things people do

• a folder of heic, and something that wants jpgfile converter
• mov and mp4 are often the same filefile converter
• QuickTime will not open it. the video is fine.file converter