Jekyll documentation to PDF with TOC

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

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.

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.