Jekyll documentation to PDF with TOC - pdf

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.
Use PrinceXML, unfortunately this is commercial product with a nasty price tag ~$500
Use WKHTMLTOPDF
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.

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.

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.

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).

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.