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.

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.

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.

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 3.1.1.0. Following components are included in the Docker image:

• TeX Live 2022

• Lua 5.4

• Pandoc 3.1.1

• Eisvogel Template 2.4.0

• Alpine Linux 3.16
  (Ubuntu 22.04.4 LTS available: pandoc/extra:3.1.1.0-ubuntu)

You can find the prebuilt Docker image (pandoc/extra:3.1.1.0), 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:

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.

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

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.

• Docker Setup Instructions (https://docs.docker.com/engine/install/)

• Markdown Tutorial (https://daringfireball.net/projects/markdown/syntax#html)

• Eisvogel LaTeX Template (https://github.com/Wandmalfarbe/pandoc-latex-template)

• Pandoc Manual (https://pandoc.org/MANUAL.html#options)

• Pandoc Extra Docker (https://hub.docker.com/r/pandoc/extra)

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.

Repository: https://github.com/maholick/md-pdf-conversion/