Markdown to PDF

A CLI utility which, as the name implies, generates a PDF from Markdown.

This is a fork of solworktech/md2pdf. I started doing some little tweaks for my own usage, it ended up deviating a lot from the original project, so I decided to start refactoring some more stuff, share it and probably mantain my own forked version.

Key differences from the original

• Built-in UTF-8 support — Liberation Sans and Liberation Mono fonts are embedded; no need for external font files or unicode encoding flags
• Embedded syntax highlighting — syntax definition files are bundled into the binary; no git submodule or -s flag needed
• Code block improvements — code blocks use Liberation Mono with background highlighting
• Restructured internals — renderer, theme, colors, fonts and highlight logic moved into internal/ packages

This package depends on two other packages:

• gomarkdown parser to read the markdown source
• fpdf to generate the PDF

---

Features

• Syntax highlighting (for code blocks) — built-in, no configuration needed
• Dark and light themes
• Customised themes (by passing a JSON file to md2pdf)
• Auto Generation of Table of Contents
• Built-in UTF-8 support (Liberation Sans / Liberation Mono)
• Pagination control (using horizontal lines - especially useful for presentations)
• Page Footer (consisting of author, title and page number)

Supported Markdown elements

• Emphasised and strong text
• Headings 1-6
• Ordered and unordered lists
• Nested lists
• Images
• Tables
• Links
• Code blocks and backticked text

Installation

Build from source:

$ go install github.com/brunofjesus/md2pdf/cmd/md2pdf@latest

Syntax highlighting

md2pdf includes built-in syntax highlighting for code blocks via embedded gohighlight syntax files. No external files or configuration needed — just annotate your code blocks with the language name.

Note: when annotating the code block to specify the language, the annotation name must match the syntax base filename.

Custom themes

md2pdf supports both light and dark themes out of the box (use --theme light or --theme dark - no config required).

However, if you wish to customise the font faces, sizes and colours, you can use the JSONs in custom_themes as a starting point. Edit to your liking and pass --theme /path/to/json to md2pdf

Auto Generation of Table of Contents

md2pdf can automatically generate a TOC where each item corresponds to a header in the doc and include it in the first page. TOC items can then be clicked to navigate to the relevant section (similar to HTML <a> anchors).

To make use of this feature, simply pass --generate-toc as an argument.

Quick start

$ go run ./cmd/md2pdf -i input.md -o output.pdf

To convert multiple MD files into a single PDF, use:

$ go run ./cmd/md2pdf -i /path/to/md/directory -o output.pdf

Additional options

--input string, -i string                  Input filename, dir consisting of .md|.markdown files or HTTP(s) URL; default is os.Stdin
--output string, -o string                 Output PDF filename; required (default: "out.pdf")
--title string, -t string                  PDF title
--theme string                             Theme to use for the PDF; Can be 'light', 'dark' or the path for a custom theme file (default: "light")
--table-of-contents, --toc                 Generate a table of contents page based on the headings in the input markdown
--horizontal-rule-new-page, --hr-new-page  Start a new page on horizontal rules (---); useful for presentations
--force-overwrite, -f                      Force overwrite of output file if it already exists
--footer                                   Print doc footer (<author>  <title>  <page number>)
--page-size string                         Page size for the PDF; can be 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'Letter', 'Legal' or 'Tabloid' (default: A4)
--orientation string                       Page orientation for the PDF; can be 'portrait' or 'landscape'; default is 'portrait' (default: "portrait")
--author string                            Author name
--log-file string                          Path to log file
--help, -h                                 show help
--version, -v                              print the version

For example, the below will:

• Set the title to My Grand Title
• Set Random Bloke as the author (used in the footer)
• Set the dark theme
• Start a new page when encountering an HR (---); useful for creating presentations
• Print a footer (author name, title, page number)

$ go run ./cmd/md2pdf -i /path/to/md \
    -o /path/to/pdf --title "My Grand Title" --author "Random Bloke" \
    --theme dark --new-page-on-hr --with-footer

Tests

The tests included in this repo (see the testdata folder) were taken from the BlackFriday package. While the tests may complete without errors, visual inspection of the created PDF is the only way to determine if the tests really pass!

The tests create log files that trace the gomarkdown parser callbacks. This is a valuable debugging tool, showing each callback and the data provided while the AST is presented.

Limitations and Known Issues

• It is common for Markdown to include HTML. HTML is treated as a "code block". There is no attempt to convert raw HTML to PDF.
• Github-flavoured Markdown permits strikethrough using tildes. This is not supported by fpdf as a font style at present.
• The markdown link title (which would show when converted to HTML as hover-over text) is not supported. The generated PDF will show the URL, but this is a function of the PDF viewer.
• Definition lists are not supported
• Text styling (font, size, spacing, style, fill colour, text colour) can be customised via the theme system. Note that fill colour only works when using CellFormat(). This is the case for tables, code blocks, and backticked text.