Troubleshooting PDFKit and wkhtmltopdf in Rails

I’ve spent the past couple of days trying to generate PDF files successfully with PDFkit and wkhtmltopdf. It’s been a frustrating process to say the least.

Tips

1. You can’t use files with any other extension than .html when passing a file to PDFKit.new, they must be .html files.

2. If you are trying to include assets in the PDF by making requests to your local server, you’ll need to run a web server capable of handling multiple processes (Unicorn or similar), otherwise the request will hang. I got around this by just including the required assets inline in the page.

3. Be careful with the file content that you’re passing to PDFKit, certain HTML syntax cannot be converted to PDF successfully.

4. If the page you are converting to a PDF is dependent on javascript generating content that might not be immediately visible, you will need to pass a javascript_delay option to PDFKit.new. E.g. :javascript_delay => 1000.

5. To have a better chance at debugging the issue causing you trouble, set the verbose option to true in a PDFkit initializer.

6. Get familiar with using wkhtmltopdf. PDFKit is just a Ruby wrapper around wkhtmltopdf, so try and reproduce the command that PDFKit is running by manually entering it in your terminal. This way you can rule out wkhtmltopdf being the troublemaker and narrow it down to an issue on the web server.