Riven

Converts GitHub Flavored Markdown files to PDFs! Feature highlights:

  • Highly readable PDFs with GitHub like theme
  • Syntax Highlighting with GitHub like theme
  • Smart page breaks
  • Smart directory based file merging
  • Page numbers (not finised yet, sorry)
  • ~~Custom CSS~~ (not finised yet, sorry)
  • ~~Covers~~ (not finised yet, sorry)
  • ~~Table of Contents~~ (not finised yet, sorry)

The gem is still under development, but it already works. In the current version the output PDF file name will always be test.pdf. This will change soon.

Prerequisites

You need wkhtmltopdf in order to generate PDFs, since that's the PDF generator backend for riven:

  • If you got a Linux Distribution or OSX and your package mangement offers wkhtmltopdf in a newer version than 0.9.9.3, then install it via your package manager.

  • If you there's no newer version, you should use the wkhtmltopdf-binary gem: gem install wkhtmltopdf-binary

After that, make sure you can execute the wkhtmltopdf command in your shell:

$ wkhtmltopdf -v

If it works, everything is nice and you may proceed with the next step. If not, please make sure, wkhtmltopdf is correctly installed and the executable is within your PATH.

Installation

Simple as usual:

$ gem install riven

Usage

Riven is designed to create documents out of a bunch of markdown files. So it may take a single markdown file or a directory with some markdown files inside. Consider that the files are merged in alphabetical order if you provide a folder. Just take a look at the following examples.

Single file to PDF

This will take your example.md and generate a example.pdf in the same directory:

$ riven example.md

Multiple files

This will take your example-1.md and example-2.md and generate a awesome.pdf in the same directory:

$ riven -o awesome.pdf example-1.md example-2.pdf

A directory

This will take your documentation directory with all it's files and generate a doc.pdf in the same directory:

$ ls
documentation/

$ ls documentation/
chapter-1-preface.md
chapter-2-general.md
chapter-3-admin-gui.md
chapter-4-commandline-interface.md
chapter-5-api.md

$ riven -o doc.pdf documentation/

$ ls
doc.pdf
documentation/

Additional Features

Custom CSS

You may give riven an additional CSS file with the -s param:

$ riven -s doc.css -o doc.pdf documentation/

Cover

You may give riven a cover MD file via the -c param, which will be prepended and not provided with a page number.

$ riven -c documentation/cover.md -o doc.pdf documentation/

Syntax highlighting

Syntax highlighting just works as usual:


```ruby
  def foo
    puts 'bar'
  end
```

The syntax highlightning is powered by coderay and is using a github theme.

Table of Contents

For an automatic generated table of contents after the cover, just add the -t param:

$ riven -t -c documentation/cover.md -o doc.pdf documentation/