Jekyll documentation to PDF with TOC

Question

I would like to write documentation using Jekyll with HTML and PDF outputs. Html can have a navigation but the PDF should have table of contents. Is there a free and easy way to do that?

The HTML part is easy but I would like to use @media print CSS for making the PDF file.

I have a few ideas how to do this.

1. Use PrinceXML, unfortunately this is commercial product with a nasty price tag ~$500
2. Use WKHTMLTOPDF
3. Use Maruku, since it is possible to do a PDF conversion using it

I would like to have multiple pages HTML and single page PDF with a TOC. Any suggestions?

Btw. Buildr has solved this problem using PrinceXML.

Sarmentose

I nearly jumped out of my seat in joy thinking that Prince had gotten so cheap but the $500 is actually for single computer, single user, interactive use.. It's still $3800 (and up) for the server license. – Himelman

Busted link to Maruku github.com/bhollis/maruku – Gaff

Answer 1

If 'free' is your most important criterion, than wkhtmltopdf is your best bet. It supports things like covers, toc, headers, footers and sections. Depending on how exotic the layout of your document will be, you most likely will run into some page-break issues, but with a bit of tinkering you should be fine.

I've been using wkhtmltopdf for a bit now, with some quite complicated documents (with javascript charts, tables, svg images, etc.) and have not run into too many issues.

Make sure you use the static version of wkhtmltopdf, as it is the only version which supports rendering of a TOC page.

Shears

Hi Pieter, I'm having quite a great experience with wkhtmltopdf too, since it is indeed very feature-rich. Only one problem though, apparently small but very important: Page breaks after headings. Any experience you have to share? (github.com/wkhtmltopdf/wkhtmltopdf/issues/…) – Moravian

Answer 2

You can use the PDFKit gem, which uses wkhtmltopdf behind the scenes. Then you can put your PDF logic in a Jekyll plugin as a generator or converter.

Wrac

Answer 3

• For generating a table of contents using Jekyll, you can use the {:toc} macro offered by markdown, or write your own textile table of contents filter if you prefer to use textile..
• For generating a PDF from Html and CSS, I have found weasyprint to be a good solution. Since they do not rely upon an external engine for rendering, they do not depend upon foreign project's roadmaps for implementing relevant features such as CSS generated content or @page CSS-declarations. (But in contrast to wkhtmltopdf, weasyprint does not parse javascript).

Forbade

Answer 4

You could also use a browser extension called Awesome Screenshot to create JPEG/PDF from a page. The extension allows you to create a full-page image or export it to PDF. With this tool, you can export all pages really quickly (and/or later combine all PDFs together to create a single document).

I am aware this is a quick & dirty solution (not perfect). E.g: while using images instead of text, the full-text search will not work. Additionally, it may require some manual work, but it does the job when you just want to read it.

Hallucinatory