How To Convert Markdown to Beautiful PDF

14. Apr 2024 — Shawn Maholick
How To Convert Markdown to Beautiful PDF

Since I’m writing documentation, tutorials and guidelines on regular basis and often spent a lot of time on formatting until I get to know Markdown. Markdown is a lightweight markup language that helps you focus on writing. I have been using Markdown for a while now and have found that it has dramatically increased my productivity. Precisely because Markdown is lightweight and easy to learn, it has become increasingly popular over the years. Another great advantage is that its simplicity makes it quite easy and efficient to convert to other formats.

A Brief Introduction to Markdown

Markdown was developed and specified by John Gruber und Aaron Swartz back in 2004 with version 1.0.1. The goal was that the source language was easy for humans to read, even before conversion. There are now several extensions and flavours of Markdown that bring more features.

Key advantages of using Markdown are:

  • Markdown is easy to learn and easy to use. You can focus on content and (once you have defined a layout) don’t have to struggle with formatting and layout.

  • You can use your favorite editor to edit Markdown (.md) files, such as Visual Studio Code, Atom, Sublime Text, which help you to focus on content, are slim and efficient.

  • You can easily search files and content, since Markdown is based on textual files and content, which is readable by humans.

  • Because Markdown is slim and efficient, it is capable to be converted in many formats, such as PDF, HTML, epub or others.

  • Since the Markdown overhead is very small and textual based, it can be synced fast and easily between various devices and services.

  • Working together with others is very easy and highly efficient, if you use a version control system like git (e. g. GitHub, GitLab) or SVN (Subversion).

  • Many content management systems, including WordPress and Kirby CMS, now support Markdown, allowing for seamless content creation and migration between platforms.

You can find an introduction to vanilla Markdown and tutorial here.

Kirby CMS, for instance, is an embodiment of simplicity, utilizing Markdown to deliver a user-friendly experience that eases content management. For those intrigued by Kirby, my recent post titled "The Power of Less: How Kirby CMS Transformed My Web Experience" delves deeper into its subtleties and strengths. You can learn more about it here.

Why Did I Deal With This?

If you a familiar with Markdown and ever wondered how to convert Markdown files to beautiful PDFs, you might find the answer by continue reading.

Yes, Markdown is simple, easy to learn and has a small overhead, but what if you have to provide documentation to the management, customers or other external parties? Text files usually don’t cause a wow effect and it makes a better impression if your documents have a reasonable format and follow the corporate design.

Back in the days I struggled with this until I stumbled across a repository called “Eisvogel” on GitHub, which contains a generic LaTeX-template which uses pandoc (a universal document conversion tool) to create beautiful PDFs, which can be customised. I tried a lot and initially used a local setup, following the documentation of the repository.

However, my demands and desire for automation grew, so I started converting our documents, which we host on GitHub, automatically by using GitHub Actions. Of course, it was inefficient to build an environment for each operation and wait 5-6 minutes to set it up, and then convert documents in 10-30 seconds per operation.

Initially I created a custom container, but since pandoc integrated the "Eisvogel" template into their pandoc/extra Docker image, I stopped maintaining the custom image and updated this post/tutorial. A new example, based on the official image can be found here.

Setup Environment

This setup converts Markdown files to beautiful PDFs using pandoc, TeX Live and the Eisvogel Markdown template within a docker container. Not all Markdown flavours are supported to pandoc limitations, but vanilla markdown works like a charm.


You need following requirements fulfilled to get the environment running:

  • Your favorite text editor

  • An AMD64 based or Mac with ARM64 CPU

  • Docker Engine (see Setup Instructions)


For this tutorial we are using the pandoc/extra container version Following components are included in the Docker image:

Using the Docker Image

You can find the prebuilt Docker image (pandoc/extra:, which is based on the above mentioned repository, on Docker Hub.

Preparing Folder Structure

I'm working with a simple folder structure for a clear and easy to use environment.
Create and folder and make sure you have following structure:

Folder/File Description
docs Contains all markdown files and assets (e.g. images).
docs/assets Contains additional assets (e.g. images or pdfs) and is optional.
output Contains generated PDFs. Folder and file names can be changed in the config files.
templates Contains the page layout and a logo (e.g. PDF backgrounds etc.)
pandoc.yaml Contains all pandoc parameter, which we want to use. See Pandoc Manual for all supported parameter/options.
eisvogel.yaml Contains all Eisvogel Template parameter, which we want to use. See Wandmalfarbe/pandoc-latex-template for all supported template variables.
You can download the example here

Pulling the Image

Download the image over the terminal/console by using the docker pull command:

[~] # docker pull pandoc/extra:

You should see following output:

[~] # docker pull pandoc/extra: Pulling from pandoc/extra
ef5531b6e74e: Pull complete 
4e821479e4b5: Pull complete 
00f1e069c9e8: Pull complete 
c6b7e74dbfd1: Pull complete 
73732c6ec5a1: Pull complete 
13d63ff5f1df: Pull complete 
984e9b553bec: Pull complete 
36f506d57a55: Pull complete 
b4a7ca1217f5: Pull complete 
057ddd0af801: Pull complete 
0e8fc7fd216f: Pull complete 
7a9e5ae8d256: Pull complete 
3e228e84fa73: Pull complete 
bc128267fb7a: Pull complete 
8ba2c6e34513: Pull complete 
331ae81764c8: Pull complete 
291f71adec64: Pull complete 
526ac1392c7e: Pull complete 
bbf7689041b4: Pull complete 
d5f22a0a9693: Pull complete 
fbb2e6fff275: Pull complete 
Digest: sha256:cc98998c5ab9a652b5c760d69c2fbf3395e063c6d0519890cd46dc3efbf9031a
Status: Downloaded newer image for pandoc/extra:

Run the Container

After we prepared the folder structure and downloaded the image, we can run our example setup with docker run.

In this configuration I specified the platform linux/amd64, because I'm working on an MacBook with ARM CPU and there is currently no ARM container available.

docker run --rm \
    --platform linux/amd64 \
    --volume "$(pwd):/data" \
    --user $(id -u):$(id -g) \
    pandoc/extra: docs/*.md --defaults pandoc.yaml --metadata-file eisvogel.yaml
Please make sure that you specify the path to the docs directory, which is mentioned folder structure. Depending on your setup, you might need to specify options for pandoc and the "Eisvogel" template.

Download the full example setup.

Example Output

After successfully running the container using the example setup, the example.pdf should be available in the output folder.

Example Output
Example Output


Markdown allows writers and developers to craft content with ease and simplicity, focusing on substance rather than the distractions of complex formatting. Pairing this with the power of Pandoc and the aesthetic finesse of "Eisvogel" elevates Markdown’s text-based files into professionally styled PDFs that resonate with clarity and sophistication.

Adopting this approach not only streamlines documentation production but also leaves a memorable impression for stakeholders and external parties who consume the final materials. With this knowledge and these tools at your disposal, you're now well-equipped to convert your Markdown files into beautiful, branded documents that reflect the diligence and attention to detail of your work.



If you like this small project and want to contribute, please feel free to add code, templates or other improvements by creating pull requests with git. The repository is public and can be accessed by anyone.


Shawn Maholick

Shawn Maholick

Seasoned Tech Expert and Software Developer Sharing Insights on Organizational Scalability and Sustainable Practices for the Modern Tech Landscape.