Riven

Converts GitHub Flavored Markdown files to PDFs! Write documentations, books, reports and documents with your editor. Publish them as PDF! It's that simple and even more powerful.

Feature highlights:

  • Riven Extended Markdown featuring includes: Structure you work!
  • Generates well readable, optimized, beautiful looking PDFs
  • Style your PDF via CSS
  • Define a special and nice looking cover page
  • Auto generated table of contents
  • Syntax Highlighting with GitHub like theme
  • Page numbers
  • Smart directory based file merging and output file naming

Prerequisites

You need wkhtmltopdf in order to generate PDFs, since that's the PDF generator backend for riven. You should use the QT patched version of wkhtmltopdf to get all the features of riven. You may also use the version without patched qt, but that will disable the following features of riven: Page numbers, table of contents, covers.

  • If you got Arch Linux, you can just install the packages wkhtmltopdf-staticand icu48 from the AUR.

  • If you got another Linux Distribution (like Ubuntu) or OSX you have compile wkhtmltopdf from the sources. See http://natepinchot.com/2014/01/31/building-static-wkhtmltopdf/. This may take some time: On my i7, 16GB RAM, SSD Notebook it took about 20 minutes.

  • Otherwise, you should download wkhtmltopdf from the official website.

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 documentation.pdf (the name is guessed from the directory name, but you may also specify a output file name via the -o param) 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 documentation/

$ ls
documentation.pdf
documentation/

Structure via includes

You may also structure your document via includes. Just define a main file and you may define as many include directives within that file and any other files (even in subdirectories) as you want.

index.md

## Just a example

This is a include:

<<[ another_file.md ]

another_file.md

More **content** in this file.

Generate the PDF via:

$ riven -o awesome.pdf index.md

Additional Features

Custom CSS

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

$ riven -s doc.css documentation/

unfortunately this CSS doesn't affect the table of contents currently, sorry for that.

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 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 and provide a headline for the table of contents:

$ riven -t "Contents" -c documentation/cover.md documentation/