Skip to content

Latest commit

 

History

History
214 lines (149 loc) · 6.16 KB

README.md

File metadata and controls

214 lines (149 loc) · 6.16 KB
Raw

Another pandoc plugin for jekyll

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.

What does it do

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.

Configuration

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.

Front Matter

Covers

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.

  • Category cover: assets/covers/the_category_slug.png
  • PDF cover: assets/covers/the_slug.pdf

Paper sizes

For 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.

Bundled articles

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.

Bibliography

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).

Layout

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="{{ page.url | remove:'.html' }}.{{ extension }}">
        {{ extension }}
      </a>
    </li>
    {% endfor %}
  </ul>

How to install

Add this snippet to your _config.yml on jekyll 1.3

gems: [ 'jekyll-pandoc-multiple-formats' ]

Alternative, see here.

How to run

Execute jekyll build normally :D