This jekyll plugin was inspired by jekyll-pandoc-plugin but it was changed to generate multiple outputs, rather than just using pandoc to generate jekyll html posts. Besides, it doesn't require the 'pandoc-ruby' gem.
It's used on En Defensa del Software Libre. Please check our repo if you like to see how it works in production.
It replaces the html generation for pandoc. This means you will have support for pandoc's markdown extensions, like ~strikethrough~ and [@cite], tables and a lot more stuff.
It'll also generate the post in other formats you like, so your blog can be made available in different formats at the same time. Epub for ebook readers, mediawiki for copy&paste to wikis, etc.
If instructed, this plugin will also generate pdfs in ready for print format.
Add to _config.yml:
markdown: pandoc
pandoc:
skip:
full: false
posts: false
categories: false
bundle_permalink: ':output_ext/:slug.:output_ext'
papersize: 'a5paper'
sheetsize: 'a4paper'
imposition: true
binder: true
covers_dir: assets/covers
signature: 20
full_file: true
flags: '--smart'
site_flags: '--toc'
outputs:
latex:
pdf: '--latex-engine=xelatex'
epub: '--epub-chapter-level=2'
lang:
ar:
all: '-V mainfont="Amiri"'
pdf: '--include-in-header=_layouts/rtl.tex'markdown: pandoc will instruct jekyll to use the pandoc html
converter.
skip allows you to skip the other formats generation and proceed
with the regular jekyll site build. You can skip some of the
generation process or all of it. Older versions of this plugin
required true or false to skip the process altogether.
full_flags if full_file is defined, these flags are used on it.
By default are set to --top-level-division=part so each category is
a different book part.
site_flags are flags applied to the html generation
flags is a string with the flags you will normally pass to pandoc on cli.
It's used on all output types.
outputs is a hash of output formats (even markdown!). You can add
output-specific flags.
imposition creates ready to print PDFs if you're creating PDF
output.
binder creates ready to print PDFs
bundle_permalink is the path of the bundled articles
papersize is the page size for PDF. You can also use this option on
the front matter.
sheetsize is the page size for ready the print PDF. You can also
use this option on the front matter.
covers_dir the directory where covers are stored. If you have a
lang defined, it will append the language to the covers_dir when
looking for a category/full site cover, so you can have localized
covers.
signature is the amount of pages per fold on the imposition version.
Specify 0 for a single fold of all the pages. You can also use this
option on the front matter.
full_file generates a single file containing all articles, sectioned
by their main category (the first one defined if many).
lang is a hash where you can define per-language flags. If you have
a lang attribute in your site config, this plugin will add the
-V lang=XX flag and any language-specific flag you want. You can
define language flags for all formats or for specific formats.
IMPORTANT: As of version 0.1.0 the syntax of the config changed.
Please upgrade your _config.yml accordingly.
Support for epub covers has been added. You can add the path to a cover on the front matter of the article to have pandoc add a cover image on the epub result.
---
cover: images/awesome.png
---For categories or posts without a cover specified, the plugin looks for
a PNG file inside the covers_dir whose file name will be the
category/post slug.
Since 0.2.0, there's also support for PDF covers. If you have a PNG cover, it will get converted to PDF. You can also provide a PDF cover as long as it's the same file name as the PNG cover.
assets/covers/the_category_slug.pngassets/covers/the_slug.pdfFor PDFs, each article can have a papersize and a sheetsize. The
papersize indicates the page size, and the sheetsize indicates the
pages per fold size.
Only A* sizes from A7 to A0 are supported for now.
---
papersize: a5paper
sheesize: a4paper
---This example will generate a 2 pages per A4 sheet.
If articles share a category, the generator will create a PDF book including all of them. The name of the category will become the title of the book.
---
category: [ 'En Defensa del Software Libre #0' ]
---The papersize will be the papersize of the first article found or the
default papersize on the _config.yml file. Same applies for
sheetsize.
NOTE: Authorship will be set to empty. This could change in the future.
If you have bibliography, pandoc recommends leaving an empty section at the end of the document if you want to have a separate section for it. For bundled articles, this plugin will remove the extra sections and create one for everything at the end.
# Bibliography
<EOF>You can also use the underlined version of the section title (aka
settext style vs atx style).
Add this liquid snippet on your _layout/post.html to generate links to the
other available formats from the post itself:
<ul>
{% for format in site.pandoc.outputs %}
{% capture extension %}{{ format | first }}{% endcapture %}
<li>
<a href="https://github.com/fauno/jekyll-pandoc-multiple-formats/blob/master/{{ page.url | remove:'.html' }}.{{ extension }}">
{{ extension }}
</a>
</li>
{% endfor %}
</ul>Add this snippet to your _config.yml on jekyll 1.3
gems: [ 'jekyll-pandoc-multiple-formats' ]Alternative, see here.
Execute jekyll build normally :D