Panache 0.2.12

Pandoc wrapped in styles

panache

build-status codefactor Pypi Known Vulnerabilities

Overview

panache adds styles to Pandoc.

The idea of panache is similar to that of panzer and Pandocomatic. It is yet another Pandoc wrapper, that allows to assemble Pandoc-commandline options, -metadata and -filter into styles. Through that, panache simplifies Pandoc calls and ensures consistency across documents.

panache is similar to others in that cascading styles may be defined in separate YAML-files and within documents.

panache is different in that its styles may contain variables and that documents may specify multiple styles / context-dependable styles.

Context Dependable Styles

Often a Markdown document is the source for different targets. For example a single document may be converted to HTML as part of a Wiki, a draft HTML file may be used while writing the document, and a standalone and self-contained HTML-file may be send via email. At the same time, all version should be rendered using the private style (as oposed to (for example) a company style).

To address this situation, panache allows documents to specify multiple styles, which get selected depending on the selected medium.

Assume, for example, a document with the following metadata-block:

---
styles_:
  drafthtml: privatedrafthtml
  finalhtml: privatefinalhtml
  wiki: wikihtml
---

Depending on the value of the command line option --medium (darfthtml, finalhtml, or wiki), panache would select either the privatedrafthtml-, privatefinalhtml- or wikihtml-style. It would then compute the commandline (options, filters and metadata) for the selected style and finally call Pandoc.

Cascading Style Definition

panache allows to define styles in separate YAML-files and within documents. The definition for a style with the name wikihtml might look like the following:

---
styledef_:
  wikihtml:
    commandline:
      template: /home/sebastian/templates/wiki-en.html
    metadata:
      build-os: Linux
    filter:
      run: pandoc-citeproc
---

A second – derived – style, that changes the template (template), may be defined by adding:

---
germanwikihtml:
  parent: wikihtml
  commandline:
      template: /home/sebastian/pandoc-templates/templates/wiki-de.html
---

to the previous styledef_ or by adding it to a separate styledef_ in another file.

Style Variables

Obviously, the style definitions above may work for the user sebastian but are likely to fail for a different user. This is where parameterized style definitions come into play.

panache uses {{ mustache }} as template engine for style files. Through that, panache allows to use “keywords” in style definitions, wich are substituted based on commandline options and some defaults. Using this, the above definition of the germanwikihtml-style may be rewritten as follows:

---
germanwikihtml:
  parent: wikihtml
  commandline:
      template: {{home}}/pandoc-templates/wiki-de.html
---

Now, if --style-var=home:/home/sebastian would be passed to panache, then template would be resolved to /home/sebastian/pandoc-templates/wiki-de.html (and as --template=/home/sebastian/pandoc-templates/wiki-de.html passed to Pandoc). Obviously, using --style-var=home:~ makes the panache-call user agnostic (in Bash).

Using regular {{ mustache }}-syntax one may express conditions and repetitions.

Installation

Options

There are two options for using panache:

• running the Python source

• running a binary version

Both options will be described below.

Python Source

Make sure the following requirements are satisfied:

• Pandoc >= 2.1

• Python >= 3.5

Use pip to install panache:

• globally

  pip install panache
  # /usr/lib/python3/dist-packages/panache/panache.py --version

  or locally:

  mkdir panache
  cd panache/
  virtualenv -p /usr/bin/python3 venv
  source venv/bin/activate
  pip install panache
  # python3 ./venv/lib/python3.6/site-packages/panache/panache.py --version

Binary

Make sure the following requirement is satisfied:

• Pandoc >= 2.1

Dowload an appropriate binary from the releases page.

Details

Default Style- and Meta-Variables

The following Style- and Meta-Variables will be added by default, if input comes from file or STDIN:

Variable	Description
panache_d ir	directory of the panache script
panache_v ersion_X.Y. Z	panache version where X, Y, Z are major, minor and patch (see Semantic Versioning)
os_X	os type where X is one of posix, nt, ce, java.
build_dat e	the date and time when panache was invoked (in the form YYYY-mm-ddTHH:MM:SSZ)

If input comes from a file the following additional Style- and Meta-Variables will be added by default:

Variable	Description
input_dir	directory of the input file
input_basename	basename of the input file
input_basename_root	basename without extension of the input file
input_basename_extension	extension of the basename
vcsreference	vcs reference of the file
vcsdate	vcs date (last change)

MORE

tbd.