Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/abemedia/jekyll-pdf
Create PDFs from Jekyll pages & documents.
https://github.com/abemedia/jekyll-pdf
Last synced: 19 days ago
JSON representation
Create PDFs from Jekyll pages & documents.
- Host: GitHub
- URL: https://github.com/abemedia/jekyll-pdf
- Owner: abemedia
- License: gpl-3.0
- Created: 2016-05-25T16:36:57.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-04-07T14:46:19.000Z (over 4 years ago)
- Last Synced: 2024-04-27T23:34:28.871Z (7 months ago)
- Language: Ruby
- Homepage: http://abemedia.co.uk/jekyll-pdf/
- Size: 35.2 KB
- Stars: 104
- Watchers: 12
- Forks: 35
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Jekyll PDF
Dynamically generate PDFs from Jekyll pages, posts & documents.
[](https://travis-ci.org/abeMedia/jekyll-pdf)
[](https://gemnasium.com/github.com/abeMedia/jekyll-pdf)
## Usage
Add `gem "jekyll-pdf"` to your `Gemfile` and run `bundle`, then add `jekyll-pdf` to your `_config.yml` like so:
```yaml
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](https://jekyllrb.com/docs/configuration/#front-matter-defaults). The following example will create PDFs for each post in your blog.
```yaml
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](http://wkhtmltopdf.org/) does. For a full list of configuration parameters it supports see http://wkhtmltopdf.org/usage/wkhtmltopdf.txt
```yaml
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:
```yaml
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:
```html
Page {{ page.pdf.page }} of {{ page.pdf.topage }}
```
### 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