Skip to content
Pandoc filter for variable substitution using Mustache syntax
Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
pandoc_mustache Remove 'dev' from version May 10, 2019
tests Update tests to use installed pandoc-mustache command Dec 26, 2017
.gitignore Gitignore another python build byproduct Dec 26, 2017
.travis.yml Add new python versions to CI tests May 10, 2019
CONTRIBUTING.md Add first draft of README Dec 26, 2017
LICENSE Update CC0 license so it is recognized by Github Dec 26, 2017
MANIFEST.in Create a setup.py to install package from pip Dec 26, 2017
README.md Set version number and switch to master branch badge Dec 27, 2017
requirements.txt Fix filter, tests for python 2.7 support Dec 25, 2017
setup.cfg Configure Travis to deploy tagged commits to PyPI Dec 26, 2017
setup.py

README.md

pandoc-mustache: Variable Substitution in Pandoc

Development Status PyPI version Python version Build Status

The pandoc-mustache filter allows you to put variables into your pandoc document text, with their values stored in a separate file. When you run pandoc the variables are replaced with their values.

Technical note: This pandoc filter is not a complete implementation of the Mustache template spec. Only variable replacement is supported: other tag types are not currently supported.

Example

This document, in document.md:

---
mustache: ./le_gaps.yaml
---
The richest American men live {{diff_le_richpoor_men}} years longer than the poorest men,
while the richest American women live {{diff_le_richpoor_women}} years longer than the poorest women.

Combined with these variable definitions, in le_gaps.yaml:

diff_le_richpoor_men: "14.6"
diff_le_richpoor_women: "10.1"

Will be converted by pandoc document.md --filter pandoc-mustache to:

The richest American men live 14.6 years longer than the poorest men, while the richest American women live 10.1 years longer than the poorest women.

Installation

Install by opening a terminal and running:

pip install -U pandoc-mustache

Python 2.7, 3.4+, pypy, and pypy3 are supported.

Usage

  1. Within a pandoc document, variables are referenced by enclosing the variable name in double "mustaches", i.e. curly brackets, like {{this}}.

  2. The variables are defined in one or more separate files, using YAML formatted key-value pairs. For example:

    place: Montreal
    temperature: '7'
  3. The pandoc document containing the mustache variables points to the YAML file (or files) which contain the variable definitions. These files are indicated using the mustache field in a YAML metadata block, typically placed at the top of the pandoc document. Absolute paths and relative paths are supported: relative paths are evaluated relative to the working directory where pandoc is being run.

    An example:

    ---
    title: My Report
    author: Jane Smith
    mustache: ./vars.yaml
    ---
    The temperature in {{place}} was {{temperature}} degrees.

    Or, with more than one file:

    ---
    title: My Report
    author: Jane Smith
    mustache:
    - ./vars.yaml
    - ./additional_vars.yaml
    ---
    The temperature in {{place}} was {{temperature}} degrees.
    The humidity was {{humidity}}%.
  4. Run pandoc and replace all variables in the document with their values by adding --filter pandoc-mustache to the pandoc command.

Tips and Tricks

  • When defining variables in YAML, there is no need to enclose strings in quotes. But you should enclose numbers in quotes if you want them to appear in the document using the exact same formatting. Some examples:

     unquoted_string: Montreal  # becomes: Montreal
     quoted_string: 'Montreal'  # becomes: Montreal
     trailingzero_num: 7.40  # becomes: 7.4
     trailingzero_string: '7.40'  # becomes: 7.40
  • If you're writing a document that reports computed numerical results, you can program your code (in R, Python, Stata, etc.) to write those numbers to a YAML file automatically each time they are generated. By referencing your numerical results using variables instead of hard-coding them into the text, the document can be updated instantly if the results change. And you can be certain that all the numbers in the output document reflect the latest results of your analysis.

Contributing

Project Status: Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.

This code is not being actively developed. It was created to fulfill my pandoc writing needs, and the current feature set is adequate for me.

If you have a bug report, you can create an issue or file a pull request. I'll look into it, time permitting.

If you have a feature request, it is unlikely that I will be able to implement it for you. You can create an issue to generate discussion. If you implement a feature, you can file pull request and I will review it eventually, as time permits. If you're interested in making major additions to the code, I'd be happy to welcome a new maintainer to the project.

License

All of the files in this repository are released to the public domain under a CC0 license to permit the widest possible reuse.

Acknowledgements

This pandoc filter was created using Sergio Correia's panflute package. The panflute repository also served as an inspiration for the organization of this repository.

Related Filters

Scott Koga-Browes' pandoc-abbreviations filter also performs variable replacement in pandoc documents, using a different syntax.

You can’t perform that action at this time.