Convert Markdown to Beautiful PDFs on macOSConvert Markdown to Beautiful PDFs on macOS

Turn Markdown files into polished, shareable PDFs on macOS with a free, open-source workflow using Pandoc, WeasyPrint, and custom CSS.

I work with Markdown files quite a bit. It's one of those formats that just makes sense when you're dealing with technical documentation, project notes, architecture decisions, or pretty much anything you want to maintain alongside your code.

It's lightweight, easy to edit, works beautifully with Git, and doesn't get in your way.

But there's one problem I've run into more than a few times.

Markdown is great for writing documentation. It's not always great for sharing it.

Sure, I can send someone a .md file or point them to a GitHub repository. But that's not always the experience I want to give someone who just needs to review a proposal, read some documentation, or share something with the rest of their team.

Sometimes, I just want a nicely formatted PDF.

And ideally, I don't want to spend 20 minutes turning something that already looks good in Markdown into something that looks good on paper.

The Gap Between Writing Documentation and Sharing It

One of the things I like about Markdown is that it lets me focus on the content rather than the formatting.

I can organize a document using headings, lists, tables, code blocks, and links without worrying too much about how everything is going to look.

That works especially well when the intended audience is other developers.

But technical documentation doesn't always stay within the development team.

Sometimes you're sharing an architecture proposal with leadership, sending implementation notes to a client, documenting a process for another department, or preparing something that people might want to print.

And while Markdown is perfectly readable to those of us who work with it regularly, it's not necessarily the best format for everyone else.

PDFs are a little more universal.

They're easy to share, generally preserve their formatting, and don't require the recipient to have a Markdown editor or know what a GitHub repository is.

The challenge is getting from one format to the other without turning it into another project.

Why Not Just Use an Online Converter?

There are plenty of websites that will convert Markdown into a PDF.

For a quick, one-off conversion, some of them work just fine.

But I wanted something I could run locally on my Mac.

Part of that is convenience. I don't particularly want to open a browser, find a conversion website, upload a file, download the result, and repeat the process whenever I make a change.

There's also the question of privacy.

Technical documentation can include internal architecture details, configuration examples, business requirements, or information that isn't necessarily intended for an external service.

I'd rather not upload that content somewhere simply because I need a PDF.

And finally, I wanted control over how the output looked.

If I'm sharing something with my team, I want it to be readable and consistent. That includes things like headings, spacing, typography, code blocks, and especially tables.

The goal wasn't just to convert Markdown into a PDF. It was to make the result something I'd actually want to share.

A Surprisingly Annoying Problem: Tables

If you've written much technical documentation, you've probably run into this.

Tables are incredibly useful for documenting configuration options, comparing approaches, outlining requirements, or presenting structured information.

And Markdown makes them relatively easy to write.

But not every Markdown-to-PDF converter does a particularly good job rendering them.

Some converters produce awkward column widths, inconsistent spacing, or tables that don't look particularly good once they're exported.

That was one of the frustrations that pushed me toward building a different solution.

I didn't need anything fancy. I just wanted the formatting I was already using in Markdown to translate into a clean, readable PDF.

And I wanted to be able to customize the appearance without manually editing the finished document.

The Solution: A Little Open-Source Tooling

After exploring a few options, I ended up putting together a small workflow built around two open-source projects: Pandoc and WeasyPrint.

Pandoc handles the document conversion, including support for GitHub Flavored Markdown.

WeasyPrint handles rendering the PDF, using CSS to control its appearance.

That combination is useful because it separates the content from the presentation.

I can continue writing in Markdown, just like I normally would, and use CSS to determine how the document should look when exported.

If I want different heading styles, better table formatting, more readable code blocks, or different page margins, I can adjust the stylesheet.

And because the process runs locally, I don't need to upload my Markdown files to a conversion website.

I also put together a Bash script to make everything easier to use from the macOS Terminal.

Rather than remembering a long conversion command, I can point the script at a Markdown file or an entire folder of documents.

The script also supports recursive directory processing, which can be handy when your documentation is spread across multiple folders in a repository.

Nothing particularly groundbreaking here. Just a small collection of tools working together to solve an annoying problem.

Why I Think This Is Particularly Useful for Development Teams

What I find interesting about this approach is how it fits into an existing development workflow.

You don't need to move your documentation into a different application.

You don't need to maintain a separate Word document or Google Doc just because someone wants a PDF.

And you don't need to manually reformat everything whenever the original Markdown changes.

Instead, Markdown can remain the source of truth.

Your team can write and review documentation in Git, maintain changes alongside the project, and generate a PDF whenever someone needs a more portable version.

There's also an opportunity to standardize the presentation.

If everyone uses the same stylesheet, the exported documents can have consistent typography, spacing, headings, and table formatting.

For teams producing a lot of technical documentation, that consistency can make a difference.

And because the underlying tools are open source, there's no need to subscribe to another service just to convert documents.

You still need to install and maintain the tools, of course, but the workflow is straightforward once it's configured.

What Does the Workflow Actually Look Like?

At a high level, it's pretty simple.

You write a Markdown file using your favorite editor.

When you're ready to share it, you run a command in Terminal.

The script takes the Markdown, processes it through Pandoc, applies your custom CSS, and generates a PDF using WeasyPrint.

The resulting PDF is saved alongside the original Markdown file.

You can do the same thing for an entire folder of .md files, including subdirectories when needed.

That's really all I wanted.

A repeatable way to turn documentation I was already writing into something that looked good enough to share.

And because the styling is configurable, I can continue refining the output without changing the original Markdown files.

Is This Better Than a Dedicated Documentation Platform?

Not necessarily.

If your team needs a full documentation portal, sophisticated collaboration tools, publishing workflows, or centralized document management, there are plenty of platforms designed for those problems.

This isn't trying to replace them.

It's a much smaller solution for a much more specific need.

I already have Markdown files. I want nice-looking PDFs. I want to generate them locally on macOS without making the process complicated.

That's the problem this solves.

And sometimes I think we overlook how valuable these smaller utilities can be.

Not every workflow needs another SaaS application or a complicated automation pipeline.

Sometimes a Bash script and a couple of reliable open-source tools are enough.

Want to Try It Yourself?

I've published the complete setup as a GitHub Gist so other developers and technical professionals can use it or adapt it for their own workflows.

The Gist includes the macOS installation instructions, the Bash conversion script, a starter CSS stylesheet, and examples for converting individual files or entire directories.

I intentionally kept the implementation there rather than turning this article into a long series of terminal commands.

That way, the Gist can remain the technical reference, and you can grab whatever pieces are useful for your own setup.

Convert Markdown to Pretty PDFs on macOS — View the Complete GitHub Gist

If you work with Markdown regularly and occasionally need to share your documentation with people who don't, this might be a handy little addition to your toolbox.