Package: pandoc-mustache
Date:May 11, 2019Contentspandoc-mustache: Variable Substitution in PandocExampleInstallationUsageTips and TricksContributingLicenseAcknowledgementsRelated Filterspandoc-mustache: Variable Substitution in PandocThepandoc-mustachefilter allows you to put variables into your
pandoc document text, with their values stored in a separate file. When
you runpandocthe variables are replaced with their values.Technical note:This pandoc filter is not a complete implementation of
theMustache template spec. Only
variable replacement is supported: othertag
typesare not
currently supported.ExampleThis document, indocument.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, inle_gaps.yaml:diff_le_richpoor_men:"14.6"diff_le_richpoor_women:"10.1"Will be converted bypandoc document.md--filterpandoc-mustacheto: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.InstallationInstall by opening a terminal and running:pip install -U pandoc-mustachePython 2.7, 3.4+, pypy, and pypy3 are supported.UsageWithin a pandoc document, variables are referenced by enclosing the
variable name in double “mustaches”, i.e. curly brackets, like{{this}}.The variables are defined in one or more separate files, using YAML
formatted key-value pairs. For example:place:Montrealtemperature:'7'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 aYAML 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 wherepandocis being run.An example:---title:My Reportauthor:Jane Smithmustache:./vars.yaml---The temperature in {{place}} was {{temperature}} degrees.Or, with more than one file:---title:My Reportauthor:Jane Smithmustache:-./vars.yaml-./additional_vars.yaml---The temperature in {{place}} was {{temperature}} degrees.The humidity was {{humidity}}%.Run pandoc and replace all variables in the document with their
values by adding--filterpandoc-mustacheto the pandoc command.Tips and TricksWhen 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: Montrealquoted_string:'Montreal'# becomes: Montrealtrailingzero_num:7.40# becomes: 7.4trailingzero_string:'7.40'# becomes: 7.40If 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.ContributingThis 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 abug report, you can create an issue or file a pull
request. I’ll look into it, time permitting.If you have afeature 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.LicenseAll of the files in this repository are released to the public domain
under aCC0
licenseto
permit the widest possible reuse.AcknowledgementsThis pandoc filter was created using Sergio Correia’spanflutepackage. Thepanfluterepository also
served as an inspiration for the organization of this repository.Related FiltersScott Koga-Browes’pandoc-abbreviationsfilter also performs variable replacement in pandoc documents, using a
different syntax.