How To Convert Markdown to Beautiful PDF24. January 2022 2022-06-04 22:35
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).
You can find an introduction to vanilla Markdown and tutorial 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.
That is why I have built a container.
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.
- TeX Live 2021 docker image (Debian Bookworm / Testing)
- TeX Live add-ons:
adjustbox babel-german background bidi collectbox csquotes everypage filehook footmisc footnotebackref framed fvextra letltxmacro ly1 mdframed mweights needspace pagecolor sourcecodepro sourcesanspro titling ucharcat ulem unicode-math upquote xecjk xurl zref
- pandoc 2.11.2
- Eisvogel template 2.0.0
- Your favorite text editor
- An x86_x64 compatible system (ARM not supported at the moment)
Document Folder Structure
For using this container you need following structure:
- /docker Contains the Dockerfile for creating docker images.
- /config Contains the yaml config files for pandoc and the Eisvogel LaTeX template (metafile).
- /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 Eisvogel LaTeX template, page layout and a logo.
You can download the sample structure here https://github.com/maholick/md-pdf-conversion.
Please clone the repo locally or if you are familar with GitHub Actions, you can use this setup to run automated PDF conversion directly on GitHub.
From the cloned directory of the repo, build the docker image. This step only needs to be performed a single time. If you don’t want to build the image by yourself, feel free to skip building and proceed with here.
docker build -t md-pdf-conversion -f docker/Dockerfile .
Now, simply create a container using following command. Name of the container of cause can be changed.
docker run -v /path/to/your/workdir/:/var/opt/pandoc --name md-pdf-conversion maholick/md-pdf-conversion:latest
If you decided to build the container by your own, you can skip the next part and proceed with Creating the Container.
You can find the prebuilt docker image (maholick/md-pdf-conversion), which is based on the above mentioned repository, on Docker Hub:
Download the image by using the docker pull command:
docker pull maholick/md-pdf-conversion
You should see following output:
[~] # docker pull maholick/md-pdf-conversion Using default tag: latest latest: Pulling from maholick/md-pdf-conversion 277c3ceb6ade: Pull complete 580a80152554: Pull complete 7bfd52c0000d: Pull complete 7f8901bd7e4b: Pull complete e52047f39c0c: Pull complete 1c092bbb5320: Pull complete cfee95d50208: Pull complete 320119eb2697: Pull complete 6bd300cf6af9: Pull complete c93bd34180d9: Pull complete 3fb5bf20a2d1: Pull complete 83cb0f8303fd: Pull complete aa9436434dc4: Pull complete be6b4cb165dd: Pull complete b6f8dc5a05d5: Pull complete e6046f25124e: Pull complete 738b8b88784f: Pull complete 34186473e003: Pull complete 414e757c63b7: Pull complete 6aa9266be2b4: Pull complete 6f6544062c50: Pull complete 5eeef9f9eed0: Pull complete 5c1ac9571595: Pull complete d4aab6faf008: Pull complete eb71361fb3a8: Pull complete efea4e718ab5: Pull complete 05229a15e1c5: Pull complete 91d3fbc55d8a: Pull complete 5661cf43c0e0: Pull complete 4b676f374ca2: Pull complete cd4f21db67ec: Pull complete 1f51504aeb7c: Pull complete Digest: sha256:43d1dfd8c23bd6cd532e47ac8a0eddda8ede4186dc90c4b17ef2a4a1828d7f4b Status: Downloaded newer image for maholick/md-pdf-conversion:latest docker.io/maholick/md-pdf-conversion:latest
Create the Container
After you downloaded the image, we need to create the container with docker run. Please make sure that you specify the path to the directory, with the above mentioned folder structure. You can choose any name for the container you want. The container is configured to start
docker create -v /path/to/your/workdir/:/var/opt/pandoc --name md-pdf-conversion maholick/md-pdf-conversion:latest
The container will be created and you should see a similar output:
[~] # docker create -v /path/to/your/workdir/:/var/opt/pandoc --name md-pdf-conversion maholick/md-pdf-conversion:latest 18a67ddaaee649d2eaa7a716608359afa13aef037f336653aa07a9d522f52707
Start the Container
Now we are ready and can start the container
[~] # docker start md-pdf-conversion md-pdf-conversion
and check if the container is running
[~] # docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 18a67ddaaee6 maholick/md-pdf-conversion:latest "/wait.sh" 2 minutes ago Up 18 seconds md-pdf-conversion
Convert Markdown to PDF
Now we are ready for our first conversion. For this we will use the example files, which are included in the repository. Please navigate to docs folder in your working directory, which you configured with the container and create the start file “.start“. The conversion starts immediately by converting all “*.md” files recursively and ordered, using the configuration in “/config“.
[/] # cd /path/to/your/workdir/docs [/path/to/your/workdir/docs] # ls 00_Lorem_ipsum.md assets/ [/path/to/your/workdir/docs] # touch .start [/path/to/your/workdir/docs] # ls [/path/to/your/workdir/docs] # ls -all ../output/ total 160 drwxrwxrwx 2 demo users 4096 2021-06-26 07:28 ./ drwxrwxrwx 6 demo users 4096 2022-01-23 21:34 ../ -rw-rw-rw- 1 demo users 146270 2022-01-24 21:12 example.pdf
You can find the converted file in the output folder of your working directory and should now see a beautiful PDF file, which was converted from Markdown, based on your adjustments within the config files.
After a successful conversion the conversion folder will be emptied. Make sure that you only copy files here.
The start-file will be removed and you can check your config for errors.
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.