Skip to content

Latest commit

 

History

History
101 lines (68 loc) · 3.7 KB

README.md

File metadata and controls

101 lines (68 loc) · 3.7 KB
Raw

Jekyll PDF

Dynamically generate PDFs from Jekyll pages, posts & documents.

Build Status Dependency Status

Usage

Add gem "jekyll-pdf" to your Gemfile and run bundle, then add jekyll-pdf to your _config.yml like so:

gems:
  - jekyll-pdf

Now add pdf: true to any page's or document's front-matter, that you'd like to create a PDF version of.

To activate Jekyll PDF for multiple pages or entire collections you can use Jekyll's front-matter defaults. The following example will create PDFs for each post in your blog.

defaults:
  -
    scope:
      path: ""
      type: "posts"
    values:
      pdf: true

Link to the PDF using the {{ page.pdf_url }} liquid variable.

Configuration

Jekyll PDF supports any configuration parameters wkhtmltopdf does. For a full list of configuration parameters it supports see http://wkhtmltopdf.org/usage/wkhtmltopdf.txt

pdf:
  cache: false | directory | default: .asset-cache
  page_size: A4, Letter, etc. | default: A4
  layout: layout | default: pdf

All configuration parameters (with exception of cache) can be overridden from your page's or it's PDF layout's front-matter.

Cache Folder

If Jekyll Assets is installed, Jekyll PDF will automatically use the same cache folder as Jekyll Assets (unless specified otherwise).

Layouts

Jekyll PDF will check for your current layout suffixed with _pdf e.g. if you're using a layout called post, it will look for _layouts/post_pdf.html, falling back to your default PDF layout (usually _layouts/pdf.html).

To override this behaviour, add the pdf_layout variable to your page's YAML front-matter. For example:

pdf_layout: my_custom_pdf_layout

Partials (Header, Footer & Cover Page)

We'll automatically look for all partials in _includes directory, e.g. header_html: pdf_header.html will tell Jekyll PDF use _includes/pdf_header.html.

Please note that wkhtmltopdf requires all partials to be valid HTML documents for example:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.6/css/bootstrap.css">
</head>
<body>
  Page {{ page.pdf.page }} of {{ page.pdf.topage }}
</body>
</html>

Supported header & footer variables

Liquid Description
{{ page.pdf.page }} Replaced by the number of the pages currently being printed
{{ page.pdf.topage }} Replaced by the number of the last page to be printed
{{ page.pdf.section }} Replaced by the content of the current h1 tag
{{ page.pdf.subsection }} Replaced by the content of the current h2 tag
{{ page.pdf.subsubsection }} Replaced by the content of the current h3 tag

Troubleshooting

Images aren't displaying in the PDF

If your images aren't displaying in the PDF, this is most likely due to the fact that wkhtmltopdf doesn't know where to look. Try prefixing your image URLs with file://{{ site.dest }}.
For asset URLs in CSS files we recommend creating a separate CSS file overriding the URLs with the prefix mentioned above.

Copyright

© 2016 Adam Bouqdib - http://abemedia.co.uk