Pandoc

The first tool you can use to convert a Markdown file to PDF is Pandoc  .

To install Pandoc and all its dependencies on my Ubuntu 11.04, I used the following command: 

1$ aptitude install pandoc texlive

Then I applied the PDF transformation on the README.md file from my openerp.buildout GitHub project  : 

1$ wget https://raw.github.com/kdeldycke/openerp.buildout/master/README.md
2$ pandoc README.md -o readme-pandoc.pdf

The result is good, but not perfect. For example code blocks with long lines don’t break at the end of the page:

PDF page from pandoc where the long apt-get command runs straight off the right edge of the paper and is cut off

While trying to solve this issue, I stumble upon another tool…

Gimli

Gimli is an utility that was explicitly written with GitHub in mind.

Gimli is written in Ruby, so let’s install it the Ruby way: 

1$ aptitude install rubygems wkhtmltopdf
2$ gem install gimli

Then we can convert our Markdown file to a PDF. The following will generate a README.pdf file in the current folder: 

1$ /var/lib/gems/1.8/bin/gimli -f ./README.md

The resulting PDF is really close to how GitHub renders Markdown content on its website. And it solve the bad code block style of Pandoc:

The same page from gimli, the long command wrapped onto a second line inside a grey code box that fits the margins

7 archived comments

Comments are closed. These were posted on Disqus, and are archived here.

  1. johnchristopher

    I don't know why but I needed to add the github css [github css][https://github.github.com/github-flavored-markdown/shared/css/documentation.css] in order to get a pdf in the style of github:

    ~ $ gimli -f file.md -s documentation.css
  2. Martoni

    Ach, that doesn't work with array. To bad :(

  3. Joseph

    when running:

    gem install gimli

    got error:

    libxslt is missing

    fixed by running:

    sudo apt-get install libxslt-dev libxml2-dev

    Best Regards,
    Joseph

  4. Joseph

    when running:

    /var/lib/gems/1.8/bin/gimli
bash: /var/lib/gems/1.8/bin/gimli: No such file or directory

    fixed by instead running:

    /var/lib/gems/1.8/gems/gimli-0.5.2/bin/gimli

    Best Regards,
    Joseph

  5. Joseph 
    /var/lib/gems/1.8/gems/gimli-0.5.2/bin/gimli -f README

    got error:

    /var/lib/gems/1.8/gems/gimli-0.5.2/bin/../lib/gimli/setup.rb:3:in `require': no such file to load -- optiflag (LoadError)
from /var/lib/gems/1.8/gems/gimli-0.5.2/bin/../lib/gimli/setup.rb:3
from /var/lib/gems/1.8/gems/gimli-0.5.2/bin/../lib/gimli.rb:5:in `require'
from /var/lib/gems/1.8/gems/gimli-0.5.2/bin/../lib/gimli.rb:5
from /var/lib/gems/1.8/gems/gimli-0.5.2/bin/gimli:5:in `require'
from /var/lib/gems/1.8/gems/gimli-0.5.2/bin/gimli:5

    instead just ran

    gimli

    Lastly, -f option doesn't seem to do anything. So a copied all the REAMDE files the current directory, renamed them to they had a .md extension and just ran gimli. gimli then processed the files correctly.

    Best Regards,
    Joseph

  6. cgr 
    mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

    To fix this error I additionally installed ruby-dev

    ~$ sudo apt install ruby-dev
  7. Þórir

    Excellent tutorial. Simple and straigth to the point.

    To get this to work on Fedora 25 I had to install some additional packages:

    To install Pandoc do:

    $ sudo dnf install pandoc texlive

    And for Gimli do:

    $ sudo dnf install rubygems ruby-devel wkhtmltopdf redhat-rpm-config zlib zlib-devel

    Then you can do:

    $ sudo gem install gimli

    I also found that wget was missing (wtf Fedora!):

    $ sudo dnf install wget