Table of contents and cover functionality #104

wants to merge 2 commits into


None yet

6 participants


There is a static build of wkhtmltopdf that allows one to add table of contents and cover options. Since I wanted that and could not find anything in the your code that supports its particular way of handling it these options, I wrote it myself. If it is supported and I missed something, then I guess you can ignore this request.

I included also a small change to line 54 of lib/pdfkit/pdfkit.rb because it was screwing up syntax highlighting in Emacs (at least with my config.) All the tests pass with this change.

I add to config options to PDFKit::Configuration:

  config.toc_options = {
    :xsl_style_sheet => "toc.xsl"

  config.cover_options = {
    :file => "cover.html"

This can also be added when a PDFKit object is initialized:'...', :toc_options => {:xsl_style_sheet => 'toc.xsl'}, :cover_options => {:file => 'cover.html'})

(The :file flag is taken out of the command line output because the output needs to be cover cover.html.)


pdfkit member

What does the output command look like? Did you try passing these options using meta tags in the head or would that not work?

# Add any kind of option through meta tags'<html><head><meta name="pdfkit-cover_option" content="cover.html" /> </head>...')

Here would be the output of what I am using it for:

/usr/local/bin/wkhtmltopdf --header-html header.html --enable-plugins --page-size Letter --header-line --footer-right [page] --margin-top 20.0 --print-media-type --header-spacing 20.0 --disable-javascript --footer-line --quiet cover cover.html toc --xsl-style-sheet toc.xsl - print.pdf

The two things are 'cover cover.html' and 'toc --xsl-style-sheet toc.xsl'. wkhtmltopdf is also picky as to where the flags are in the command.

I did not think of trying the tag approach. However, I did give it a try now, and it looks as if it doesn't work (at least for what I tried.)

I should also support the meta functionality if you decide to add this.


The problem with using PDFKit's current meta tag options is:

  • Like bolsen noted above, wkhtmltopdf is picky about where the flags are placed
  • currently PDFKit appends '--' to the options during initialization of the output and both 'cover' and 'toc' do not take the common '--' flag delimiter. This is a bit annoying on wkhtmltopdf's part, but necessary since the cover is processed separately so that it is not counted in the page count and the header/footers are not processed with it.

I would like to see this pull request merged into the master branch since wkhtmltopdf now has the static builds available for 0.11.0 and many people, like myself, need the new features.


I think this commit could be improved a bit to follow standard conventions so that the cover and toc options can be passed via the meta tags. That would require these two particular options not being normalized with the '--' flag delimiters. I'll see if I can find a work around for this.

pdfkit member

Where does this stand? Let's move this forward or close the PR.

pdfkit member

There's been no response so I'm closing this. If someone wants to come along and revive this, please at least rebase the request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment