panache
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_dir |
directory of the panache script |
panache_version_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_date |
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.