Pandoc wrapped in styles
Project description
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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.