Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

Pandoc wrapped in styles

Project description

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:

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:

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
Panache-0.2.12-py3-none-any.whl (10.6 kB) Copy SHA256 hash SHA256 Wheel py3

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page