Use multiple input files; improved manual

In release 0.2.5.0 three changes take effect:

1. You can tell pandocomatic to use multiple input files (#65). This allows you to separate a large input file into a number of smaller files, which is more convenient. For example, if you're writing a book, you could write each chapter in a separate file and convert the whole with:

   pandocomatic -i frontmatter.md -i ch1 -i ch2 -i ch3 -i ch4 -i ch5 -o book.html

2. Pandocomatic warns when an input file (or multiple input files concatenated) do contain multiple YAML metadata blocks with a pandocomatic_ property in it. Pandocomatic will use the first pandocomatic_ property it encounters and discards the others.

3. The manual has been updated (#61) and improved.

Note. From this version on, pandocomatic only supports Ruby version 2.4.4 and up; Ruby version 2.3 and lower are no longer supported because these Ruby versions have reached end-of-life.

As usual comments are welcome!

Using commands on PATH as preprocessors and postprocessors

Besides some minor improvements, release 0.2.4.0 contains one change that justifies bumping the version from 0.2.3.x to 0.2.4.0: commands on your PATH can now also be used as preprocessors and postprocessors. It is a relatively small change, though, and existing pandocomatic templates should work the same as before.

Improved Windows support

Pandocomatic now supports specifying local and global paths in templates on the Windows operating system:

• Use .\subdir\file.txt for a local path
• Use C:\path\to\file.txt for a global path

Note. you might need to escape the backslash with a backslash. For example C:\\path\\to\\file.txt instead of C:\path\to\file.

Automatically rename output files

In this release a small feature is added that is most useful when using pandocomatic as a static site generator. Of course, pandocomatic being pandocomatic, it can also be used to convert single files.

When generating websites I often want to output my pages to both HTML and PDF, the latter to be used as a "print page". On the web it is a convention that when opening a directory, the index.html file in that directory is served. As a result, I have setup my source directory as follows:

• topic1
  • index.md
  • some assets
• topic2
  • index.md
• ...

These index.md files are converted to index.html and that is great. However, I do not want my "print pages" to be named index.pdf. Instead, I'd rather they are named after the directory they're in, like topic1.pdf.

To enable this use-case, I added the virtual pandoc option rename. It takes as argument a path to a rename script. The rename script is send the original destination via STDIN and is supposed to output the renamed destination to STDOUT. For the example above, my rename script looks like:

#!/usr/bin/env ruby

current_dst = $stdin.read
current_dst_dir = File.dirname current_dst
current_dst_filename = File.basename current_dst
current_dst_extname = File.extname current_dst

dirname = File.split(current_dst_dir).last

if current_dst_filename.start_with? "index" and not dirname.nil?
    puts File.join(current_dst_dir, "#{dirname}.#{current_dst_extname}")
else 
    puts current_dst
end

Automatically convert a file to multiple matching templates

From version 0.2.2.0 onward you can configure pandocomatic to convert a file with all matching global templates rather than with only the first matching global template: use the match-files setting in your pandocomatic configuration files.

If match-files has value all, it will convert a file with all matching templates. If it has value first or is not (well) defined, the original behavior of converting a file with the first matching template is used.

Note that any use-template statements in an input file will take precedence over this setting. The setting match-files is used mostly for converting whole directory trees.

For example, I use this setting to generate a website. Each input markdown file is now automatically converted to HTML and to PDF to offer a print version of the HTML page!

Furthermore, I fixed some issues with converting only modified files.

Feed-back and comments welcome.

Control your extensions with pandocomatic

In version 0.2.1 pandocomatic allows you finer control what extension the generated output file will have:

• Output formats have a default extension. For example, latex maps to tex, beamer maps to tex, plain maps to txt, and so on.

• Pandocomatic adds a virtual output format pdf, which uses the value of the pandoc option pdf-engine to determine the actual output format (latex, context, troff, html). If the pdf engine is not specified, the actual output format defaults to latex.

• If the pandoc output option is specified, its value takes precedence over any other options that might set the extension.

• If you want to set the extension of the output file without specifying the output option—which is not an option that works well with the general nature of pandocomatic templates—, pandocomatic adds the virtual pandoc option use-extension. Its value will be used as the extension of the output file. Unless the output option is being used, of course. For example, the following pandoc configuration will generate a PDF presentation using beamer:

  pandoc:
      from: markdown
      to: beamer
      use-extension: pdf
  

Furthermore, extensions to the output format can be added and removed by using pandoc's +EXTENSION and -EXTENSION mechanism. This did not work before. For example, you can now specify the to option like to: latex+smart-old_dashes.

As usual, comments and feed-back are welcome!

Extensible templates, fixes, and improved documentation

Since the last release earlier this year a lot has happened to pandocomatic. Besides a large amount of bug fixes, the template engine has been improved and the manual rewritten!

Futhermore, pandocomatic is compatible with pandoc2.

Comments are welcome.

Highlights

• Template engine

  • Templates can be extended; a template can extend one or more templates. This allows you to setup a modular set of (re)usable template components. For example, in the template definition below, the my-webpage templates builds on the author template (to mix in my name as author), the today template (to mix in today's date) and the webpage template (with general settings to convert to HTML):

    templates:
         author:
             metadata:
                 author: Huub de Beer
         today:
             preprocessors:
                 -   preprocessors/today.rb
         webpage:
             glob: ['*.md']
             pandoc:
                 to: html
                 toc: true
                 css:
                     - assets/style.css
             postprocessors:
                 - postprocessors/tidy.sh
         my-webpage:
             extends: ['author', 'today', 'webpage']
             pandoc:
                 to: html5
                 bibliography: 'assets/my-bibliography.bib'
    

  • Added the metadata section to template definitions, allowing you to set common metadata such as an author, keywords, language, and so on (see example above)

  • Added the setup and cleanup sections, which are a list of scripts to be run before the conversion process is started and after it has finished. This can be used to setup or clean up the environment needed for a conversion.

• Using templates
  • A document can use multiple templates. The document will be converted once for each of these templates
  • All template sections can be customized in a document rather than only the pandoc section.
• Error reporting
  • pandocomatic now exits with a status code <> 0 when something went amiss.
  • warnings during conversion are printed to STDERR rather than ignored
• Documentation
  • There is a full documentation coverage of pandocomatic's code base
  • The manual has been rewritten to cover all the new features and improvements.

Use multiple templates with pandocomatic + bugfixes

I am happy to announce a new version of pandocomatic: 0.1.3!

This release is mainly a bug fix release, but I've also added a feature to use multiple templates. Assuming you have defined a web and a print template that convert an input file to HTML or PDF respectively, the following input file will be converted to both formats:

---
title: Working with pandocomatic is fun!
pandocomatic_:
    use-template:
    - web
    - print
...

Now you can **use** pandocomatic with **multiple** templates!

Bugs squashed:

• pandoc filters also use PATH to find executables;
• multi-word pandoc options can be specified with - or _;
• YAML metadata block delimiters can end with whitespace (tabs and spaces)

Feedback welcome!

Start using "pandocomatic_" YAML property instead of "pandocomatic"

As pointed out by Joseph on the pandoc discuss mailing list, pandoc uses the convention to ignore all metadata properties ending with an underscore (_) for use by external processors. In this new release, I made pandocomatic adhere to this convention.

To extend a template or specify pandoc options or a processor in a pandoc markdown file it is now recommended to use a pandocomatic_ YAML property. For backwards compatibility, the property name pandocomatic still works and will keep on working in the 0.1.x series.

Pandocomatic Improved!

I am happy to announce the immediate release of pandocomatic 0.1.1. This is a major rewrite compared to the 0.0.x series of pandocomatic while keeping backwards compatibility. Automating the use of pandoc is now easier than before.

What is pandocomatic

Pandocomatic is a tool to automate the use of pandoc. With pandocomatic you can express common patterns of using pandoc for generating your documents. The two typical use cases of pandocomatic are:

1. automating setting up and running pandoc for a series of related papers, and

2. using pandocomatic as a static site generator.

   Notable improvements

• pandocomatic now gives feedback on the conversion process it is running.
• it also gives meaningful feedback if something goes wrong
• it has new options:
  • --modified-only to only convert files that have been changed since the last time pandocomatic has run
  • --dry-run to investigate the conversion process without actually running it
  • --quiet to skip the feedback if everything goes without errors
• and it has an extensive manual and an updated README

Install

To start using pandocomatic you can install it by running:

 gem install pandocomatic

Usage

Convert a single file

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

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

Convert a directory

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

Have fun automating your use of pandoc!