Jekyll documentation to PDF with TOC

问题:

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.

回答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.

回答2:

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

回答3:

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.