Pandocomatic is a tool to automate using pandoc. With pandocomatic you can express common patterns of using pandoc for generating your documents. Applied to a directory, pandocomatic can act as a static site generator. For example, this manual and the website it is put on are generated using pandocomatic!

I use pandoc a lot. I use it to write all my papers, notes, websites, reports, outlines, summaries, and books. Time and again I was invoking pandoc like:

pandoc --from markdown \
  --to html5 \
  --standalone \
  --csl apa.csl \
  --bibliography my-bib.bib \
  --mathjax \
  --output result.html \
  source.md

Sure, when I write about history, the CSL file and bibliography changes. And I do not need the --mathjax option like I do when I am writing about mathematics education. Still, all these invocations are quite similar.

I already wrote the program do-pandoc.rb as part of a Ruby wrapper around pandoc, paru. Using do-pandoc.rb I can specify the options to pandoc as pandoc metadata in the source file itself. The above pandoc invocation then becomes:

do-pandoc.rb source.md

It saves me from typing out the whole pandoc invocation each time I run pandoc on a source file. However, I have still to setup the same options to use in each document that I am writing, even though these options do not differ that much from document to document.

Pandocomatic is a tool to re-use these common configurations by specifying a so-called pandocomatic template in a YAML configuration file. For example, by placing the following file, pandocomatic.yaml in pandoc's data directory:

templates:
  education-research:
    preprocessors: []
    pandoc:
      from: markdown
      to: html5
      standalone: true
      csl: 'apa.csl'
      toc: true
      bibliography: /path/to/bibliography.bib
      mathjax: true
    postprocessors: []

I now can create a new document that uses that configuration by using the following metadata in my source file, on_teaching_maths.md:

 ---
 title: On teaching mathematics
 author: Huub de Beer
 pandocomatic_:
   use-template: education-research
   pandoc:
     output: on_teaching_mathematics.html
 ...
 
 and here follows the contents of my new paper...

To convert this file to on_teaching_mathematics.html I now run pandocomatic as follows:

pandocomatic -i on_teaching_maths.md

With just two lines of pandoc metadata, I can tell pandocomatic what template to use when converting a file. You can also use multiple templates in a document, for example to convert a markdown file to both HTML and PDF. Adding file-specific pandoc options to the conversion process is as easy as adding a pandoc property with those options to the pandocomatic_ metadata property in the source file.

Note that the pandocomatic YAML property is named pandocomatic_. Pandoc has the convention that YAML property names ending with an underscore will be ignored by pandoc and can be used by programs like pandocomatic. Pandocomatic adheres to this convention. However, for backwards compatibility the property name pandocomatic still works, it just will not be ignored by pandoc.

Once I had written a number of related documents this way, it was a small step to enable pandocomatic to convert directories as well as files. Just like that, pandocomatic can be used as a static site generator!

Pandocomatic is free sofware; pandocomatic is released under the GPLv3. You find pandocomatic's source code on github.

Pandocomatic is installed through RubyGems as follows:

gem install pandocomatic

You can also download the latest gem pandocomatic-0.1.3.3 from github and install it as follows:

cd /directory/you/downloaded/the/gem/to
gem install pandocomatic-0.1.3.3.gem

Pandocomatic builds on paru, a Ruby wrapper around pandoc, and pandoc itself, of course.

Convert hello.md to hello.html according to the configuration in pandocomatic.yaml:

pandocomatic --config pandocomatic.yaml -o hello.html -i hello.md

Generate a static site using data directory assets, but only convert files that have been updated since the last time pandocomatic has been run:

pandocomatic --data-dir assets/ -o website/ -i source/ -m

Generate the markdown files for pandocomatic's manual and its github repository README:

git clone https://github.com/htdebeer/pandocomatic.git
cd documentation
pandocomatic -d data-dir -c config.yaml -i README.md -o ../README.md
pandocomatic -d data-dir -c config.yaml -i manual.md -o ../index.md

Be careful to not overwrite the input file with the output file! I would suggest using different names for both, or different directories. Looking more closely to the pandocomatic configuration file config.yaml, we see it contains one template, mddoc:

templates:
  mddoc:
    pandoc:
      from: markdown
      to: markdown
      standalone: true
      filter: 
      - filters/insert_document.rb
      - filters/insert_code_block.rb
      - filters/remove_pandocomatic_metadata.rb

The mddoc template tells pandocomatic to convert a markdown file to a standalone markdown file using three filters: insert_document.rb, insert_code_block.rb, and remove_pandocomatic_metadata.rb. The first two filters allow you to include another markdown file or to include a source code file (see the README listing below). The last filter removes the pandocomatic metadata block from the file so the settings in it do not interfere when, later on, manual.md is converted to HTML. These filters are located in the filters subdirectory in the specified data directory data-dir.

However, the mddoc template converts from and to pandoc's markdown variant, which differs slightly from the markdown variant used by Github for README files. Luckily, pandoc does support writing Github's markdown variant. There is no need to create and use a different template for generating the README, though, as you can override all template's settings inside a pandocomatic block in a markdown file:

 ---
 pandocomatic_:
   use-template: mddoc
   pandoc:
     to: markdown_github
 ...
 
 # Pandocomatic—Automating the use of pandoc
 
 ::paru::insert introduction.md
 
 ## Why pandocomatic?
 
 ::paru::insert why_pandocomatic.md
 
 ## Licence
 
 ::paru::insert license.md
 
 ## Installation
 
 ::paru::insert install.md
 
 ## Examples
 
 ::paru::insert usage_examples.md
 
 ## More information
 
 See [pandocomatic's
 manual](https://heerdebeer.org/Software/markdown/pandocomatic/) for more
 extensive examples of using pandocomatic. Notably, the manual contains two
 typical use cases of pandocomatic:
 
 1.  [automating setting up and running pandoc for a series of related papers](https://heerdebeer.org/Software/markdown/pandocomatic/#automating-setting-up-and-running-pandoc-for-a-series-of-related-papers), and 
 2.  [using pandocomatic as a static site
      generator](https://heerdebeer.org/Software/markdown/pandocomatic/#using-pandocomatic-as-a-static-site-generator).

Here you see that the README uses the mddoc template and it overwrites the to property with markdown_github.

Similarly, in the input file manual.md, an extra filter is specified, 'number_chapters_and_sections_and_figures.rb', to number the chapters and sections in the manual, which is not needed for the README, by using the following pandocomatic metadata in the manual input file:

pandocomatic_:
  use-template: mddoc
  pandoc:
    filter: 
    - 'filters/number_chapters_and_sections_and_figures.rb'

Pandocomatic allows you to generalize common aspects of running pandoc while still offering the ability to be as specific as needed.

See pandocomatic's manual for more extensive examples of using pandocomatic. Notably, the manual contains two typical use cases of pandocomatic:

1. automating setting up and running pandoc for a series of related papers, and
2. using pandocomatic as a static site generator.