Category Archives: Writing

Create a PDF written in Markdown with Pandoc

It is possible to create professional Looking PDF written in Markdown with Pandoc. I feel that writing in Markdown is really intuitive for developpers, it is just you with your favorite text Editor (Notepad++ for example), no overwhelming GUI, no formatting, no distractions, just you and your content (if you want to push the no distraction part to the Limit check WriteMonkey). The Problem being Markdown was created for the Internet and has become quite popular, but many of us still live in the old world, where HTML and CSS has no place, the Standards still being Microsoft Office and PDF documents.

“What the hell did you send me?”

My colleagues when I send them something that is neither pdf nor docx

In my opinion the best part is that since you are working only with a text source, you can get an actual diff for your document. As an engineer working in safety, this might be the most important feature, because when a document has been changed, I want to know exactly what has been changed, text, title, table, Image, link… This has been a real pain with regular Tools such as Acrobat Reader. Microsoft Office and even Team Foudation Server! But when you are working with a text source the diff is really easy, for example with WinMerge. It is not pretty since there is no formatting but it is very exact and usually also a great deal faster.

The implementation

One (imperfect) solution to this problem is the conversion from markdown to pdf with pandoc. It uses the LaTeX engine for formatting, so one can add some TeX headers / footers for configuration. You Need to install Pandoc, a TeX engine (I installed MiKTeX) and a bunch of TeX libraries, which will be prompted when you run pandoc. I then run a Batch file from the console to create the final pdf:

:: ========================================= ::
:: PDF Erstellung Markdown -> Pdf mit Pandoc ::
:: ========================================= ::
::
:: This batch file converts a markdown file %1% (.md) into a "pretty" pdf file %2%.
::
:: Markdown:
:: ---------
:: Markdown:     https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
::
:: Programs needed:
:: ----------------
:: Pandoc:       https://pandoc.org/installing.html
::               https://pandoc.org/MANUAL.html
:: MiKTeX:       https://miktex.org/download
::
:: Remarks:
:: -------
:: - a lot of needed non-standard MiKTeX packets will be automatically downloaded during the first run
:: - the pdf creation is slow, especially when you include images
:: - this batch returns an error if the target pdf file already exists, it is your responsibility to make sure it does not exist
::
:: Online Documentation:
:: ---------------------
:: - https://pandoc.org/MANUAL.html#extension-yaml_metadata_block
:: - https://pandoc.org/MANUAL.html#extension-multiline_tables
:: - https://learnbyexample.github.io/tutorial/ebook-generation/customizing-pandoc/
:: - https://github.com/learnbyexample/learnbyexample.github.io/tree/master/files/pandoc_pdf
:: - https://jdhao.github.io/2019/05/30/markdown2pdf_pandoc/
:: - https://johngodlee.github.io/2019/01/29/float-latex.html
::
:: Example:
:: --------
:: > CreatePdfFromMd SomeMarkdownFile.md PrettyPdf.pdf

pandoc --toc -N^
       --include-in-header style\disablefloat.tex^
       --include-in-header style\inline_code.tex^
       --include-in-header style\bullet_style.tex^
       --highlight-style style\pygments.theme^
       -V colorlinks^
       -V urlcolor=NavyBlue^
       -V toccolor=NavyBlue^
       -V geometry:a4paper^
       -V geometry:margin=2cm^
       -V mainfont="Cambria"^
       --pdf-engine=xelatex^
       -f markdown+yaml_metadata_block+multiline_tables+grid_tables^
       -s %1%^
       -o %2%

:: Erklärung der Parameter:
:: ------------------------
:: --toc                                         Table of Content
:: -N^                                           Number headers
:: --include-in-header style\disablefloat.tex^   Pictures will be added exactly where they are defined (no floating)
:: --include-in-header style\chapter_break.tex^  Each chapter begins on a new page
:: --include-in-header style\inline_code.tex^    Special formatting style for Inline Code (grey background)
:: --include-in-header style\bullet_style.tex^   Bullet style
:: --highlight-style style\pygments.theme^       General style (font, size, color, etc.)
:: -V colorlinks^                                Link/Hyperlink will be colored
:: -V urlcolor=NavyBlue^                         URL blue
:: -V toccolor=NavyBlue^                         Table of content blue
:: -V geometry:a4paper^                          A4 Format
:: -V geometry:margin=2cm^                       Margin 2cm
:: -V mainfont="Cambria"^                        Font "Cambria"
:: --pdf-engine=xelatex^                         used pdf-engine (Xelatex is included in MiKTeX)
:: -f markdown+                                  Source file is markdown
::    yaml_metadata_block+                       Source contains a YAML Meta Datablock (contains information for the cover, see https://pandoc.org/MANUAL.html#extension-yaml_metadata_block)
::    multiline_tables+                          Allow usage of multiline tables (see https://pandoc.org/MANUAL.html#extension-multiline_tables)
::    grid_tables^                               Allow usage of grid tables (see https://pandoc.org/MANUAL.html#extension-grid_tables)
:: -s %1%                                        Source file, Markdown
:: -o %2%                                        Destination file, PDF

Limitations

  • PDF creation must be triggered from the console
  • No live view, little overview for long documents
  • PDF creation relatively long when the document contains images
  • must install Pandoc, MiKTeX
  • LaTeX Header for configuration (I find LaTeX very cryptic)
  • PDF not editable, which means every quick change leads to a new PDF generation

Advantages

  • editing a text file is very fast, no distractions
  • create your Batch file once, use it forever
  • Markdown editing is simple and can be read without creating a pdf
  • pdf looks professional
  • lightweight documents: easy for versioning, easy for comparing
  • include external images: always up-to-date

Links

Markdown syntax

Creating a PDF with Pandoc