pelidoc/README.md

Pandoc Generator (Pelidoc)

A Pelican plugin to use Pandoc software.

Pandoc is a powerful tool to transform text from different formats (e.g. ReST, Markdown) to others. It is really helpful to generate PDF or EPUB. It also can easily replace the "official" PDF plugin.

This plugin provides a powerful interface to handle document generation through Pandoc.

Markdown parsing is done in MultiMarkdown to be able to parse metadata information easily.

Installation

You need to have Pandoc (!) and pypandoc, a Python module wrapper for Pandoc, installed on your system. You can install pypandoc with pip:

$ pip install pypandoc

Then, put the plugin directory in your plugin directory. For instance, create a ./plugins directory in your Pelican project and add these lines in your pelicanconf.py file:

PLUGIN_PATHS = ['plugins']
PLUGINS = ['Pelidoc']

Obviously, you'll have to adapt instructions if you already have installed some plugins.

To use this plugin then, you'll need to set a PANDOC_OUTPUTS configuration variable. It is a dictionary where the keys are the output formats and the values are the corresponding destination directories. For instance:

PANDOC_OUTPUTS = {
    'pdf': 'pdfs',
    'epub': 'epubs',
}

Note you'll have to modify your theme template to support download of files. Here is a snippet to download files (PDF or EPUB) of a specific article. You can put it in the templates/article_infos.html file (or similar) of your theme:

{% if 'pdf' in PANDOC_OUTPUTS or 'epub' in PANDOC_OUTPUTS %}
    <div class="entry-download">
        {% if 'pdf' in PANDOC_OUTPUTS %}
            <a href="{{ SITEURL }}/{{ PANDOC_OUTPUTS['pdf'] }}/{{ article.slug }}.pdf">Download as PDF</a><br />
        {% endif %}
        {% if 'epub' in PANDOC_OUTPUTS %}
            <a href="{{ SITEURL }}/{{ PANDOC_OUTPUTS['epub'] }}/{{ article.slug }}.epub">Download as EPUB</a>
        {% endif %}
    </div>
{% endif %}

How-to contribute

• Fork the project Git repository ;
• Please open a ticket on the bug tracker so we can discuss about your bug / feature ;
• Create a dedicated branch for your fix (git checkout -b is your friend) ;
• Commit your work, push your branch upstream (git push --set-upstream origin your_branch_name) and do a pull request.

Note there's a bunch of TODOs in the source code that you may fix.

Credits

• Pelican by Alexis Métaireau ;
• Pelican plugins for the code basis (especially PDF plugin!)
• pypandoc by Juho Vepsäläinen ;
• Pandoc Reader, another Pandoc plugin for Pelican but a bit less powerful, by Hinrich B. Winther.
• And, obviously, Pandoc by John MacFarlane.