Panache 0.2.11

Pandoc wrapped in styles

panache

build-status codefactor Known Vulnerabilities

https://pypi.org/project/Panache/

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 to a friend. 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 a commandline option.

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 (e.g. darfthtml, finalhtml, or wiki), panache would select either the privatedrafthtml-, privatefinalhtml- or wikihtml-style. It would then compute the commandline, 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, 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 may be handy.

panache uses {{ mustache }} as template engine. Through that, panache allows to use “tags” 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.0

• Python >= 3.4 (incl. pyyaml, pystache)

• [git]

• [virtualenv]

Get panache.py by either:

• getting the latest release from the releases page or

• cloning the github-repository:

  git clone https://github.com/sebogh/panache.git

Run panache.py.

Binary

Make sure the following requirement is satisfied:

• Pandoc >= 2.1

Dowload the latest binary from the releases page and run panache.exe (Windows) or panache (Linux).

Details

Default Style- and Meta-Variables

The following Style- and Meta-Variables will be added by default, if input comes from 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.