How to convert Markdown + CSS -> PDF?

Question

I'm trying to convert a Markdown file into a PDF. I'm looking for only two things:

• A way to easily change the style of the pdf (for example with a CSS file)
• A syntax highlighter for code blocks

What tools can I use for that? I tried Pandoc, but it uses Latex for the formatting which is not easy to use.

Solution 1

Pandoc can convert your Markdown to HTML, but the styling/layout is a different topic. If you want to produce a PDF but use CSS for styling, you need something that can interpret CSS. That is either use a browser and print to PDF, pay for Prince or try wkhtmltopdf (see also print-css.rocks). Btw, pandoc can also use wkhtmltopdf now:

pandoc -t html --css mystyles.css input.md -o output.pdf

But I suspect if you want a beautifully-typeset PDF for free you'll have to learn LaTeX or ConTeXt which is a modern and more self-contained replacement for LaTeX, both can be used with pandoc. See creating a PDF with pandoc.

You can also give PanWriter a try: a markdown editor I built, where you can inject CSS and export the PDF from the paginated preview.

Solution 2

There is really nice and simple tool for browsing Markdown documents which additionally supports export to PDF features:

GFMS - Github Flavored Markdown Server

It's simple and lightweight (no configuration needed) HTTP server you can start in any directory containing markdown files to browse them.

Features:

• full GFM Markdown support
• source code syntax highlighting
• browsing files and directories
• nice looking output (and configurable CSS style sheets)
• export to PDF (best-looking markdown-to-pdf output I've ever seen)

gfms -p 8888

wget "http://localhost:8888/file.md?pdf" -O file.pdf

Solution 3

With the right settings, pandoc does a pretty good job, but is still missing the grey background underneath the code blocks which I'd really like it to have :(. Following the lead of @mb21's answer, here's what I came up with for a pretty decent pandoc command for GitHub Flavored Markdown (gfm).

Tested on Ubuntu 20.04:

sudo apt update
sudo apt install pandoc
sudo apt install wkhtmltopdf  # a dependency to convert HTML To pdf
wget https://raw.githubusercontent.com/simov/markdown-viewer/master/themes/github.css

# Convert test.md to test.pdf using the github.css CSS style theme
pandoc -f gfm -t html5 --metadata pagetitle="test.md" --css github.css \
test.md -o test.pdf

The wget command is to download the github.css GitHub CSS formatting theme file from here: https://github.com/simov/markdown-viewer/tree/master/themes. It is part of the Markdown Viewer Chrome plugin here, which I wrote about in my other answer here.

Breakdown of the pandoc command from above:

-f gfm    # from format = Github Flavored Markdown
-t html5  # to format = html5
--metadata pagetitle="test.md"  # html output format (-t html) requires a 
    # mandatory html title, so just set it to the input file name:
    # "test.md"
--css github.css  # use the github.css file as the CSS styling file for
                  # the html output
test.md      # this is the INPUT markdown (Github Flavored Markdown) file
-o test.pdf  # save the OUTPUT PDF as test.pdf 

Sample markdown file, test.md:

Snippet from my project here: https://github.com/ElectricRCAircraftGuy/eRCaGuy_hello_world/blob/master/markdown/github_readme_center_and_align_images.md

## 1.1. Align images left, right, or centered, with NO WORD WRAP:

This:

```html
**Align left:**
<p align="left" width="100%">
    <img width="33%" src="https://i.stack.imgur.com/RJj4x.png"> 
</p>

**Align center:**
<p align="center" width="100%">
    <img width="33%" src="https://i.stack.imgur.com/RJj4x.png"> 
</p>

**Align right:**
<p align="right" width="100%">
    <img width="33%" src="https://i.stack.imgur.com/RJj4x.png"> 
</p>
```

Produces this:

**Align left:**
<p align="left" width="100%">
    <img width="33%" src="https://i.stack.imgur.com/RJj4x.png"> 
</p>

**Align center:**
<p align="center" width="100%">
    <img width="33%" src="https://i.stack.imgur.com/RJj4x.png"> 
</p>

**Align right:**
<p align="right" width="100%">
    <img width="33%" src="https://i.stack.imgur.com/RJj4x.png"> 
</p>

If you'd like to set the text itself to left, center, or right, you can include the text inside the `<p>` element as well, as regular HTML, like this:

```html
<p align="right" width="100%">
    This text is also aligned to the right.<br>
    <img width="33%" src="https://i.stack.imgur.com/RJj4x.png"> 
</p>
```

Pandoc conversion command from above:

pandoc -f gfm -t html5 --metadata pagetitle="test.md" --css github.css \
test.md -o test.pdf

Output PDF screenshot:

Not quite as good as Markdown Viewer, as its still missing the grey background under the code blocks (see what that looks like in my other answer here), but it looks pretty good!

See also:

1. [my answer] SuperUser: How Can I Convert Github-Flavored Markdown To A PDF

Solution 4

You can use gh-md-to-html for this, which is a command line tool that does exactly what you want (full disclosure: I'm the author).

You can install it by installing wkhtmltopdf and by then using

pip3 install gh-md-to-html[pdf_export]

And then use

gh-md-to-html path_to_your_file.md -p <name>.pdf -c path_to_your_css.html

Let's dissect what the individual parts of this command do:

• The -p option declares under which file name to save the resulting pdf file; the "<name>" is automatically replaced with the name of your input file.
• The -c option is a path to a html-file which contains css within <style>-tags, which will be embedded into the resulting html file before said file is converted to pdf.

Under to hood, gh-md-to-html converts the file to html and then to pdf using wkhtmltopdf, as the name suggests.

The resulting pdf file is, in any case, styled similar to how GitHub styles their README files; if you want to disable that so you can dictate the styling as a whole using you custom css, you can supply the option -s false to the command, which disables the default styling. Code blocks are properly syntax highlighted in both cases, though.

The conversion process is done partially online (using GitHub's markdown REST API); in case you don't want that, you can use pip3 install gh-md-to-html[offline_conversion] and then run gh-md-to-html with the -o OFFLINE option.

View more solutions