Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Minimal script that runs pandoc with the options it finds in the YAML metadata of the input markdown file. For example:


with the following

title: my document
    standalone: true
    output: test.html
      - foo.css
      - bar.js
    toc: true
    toc-depth: 3
    output: test.pdf
    template: letter.tex
      fontsize: 12pt

# my content

Will execute:

pandoc --standalone --output test.html --include-in-header foo.css --include-in-header bar.js

Note how panrun defaults to using the first key in the YAML, in this case html.


panrun input-file [pandoc-options]

You can also supply more options, but only after the input file. They will be forwarded to pandoc. Panrun also looks at the -o (--output) and -t (--to) options to determine the output format. For example:

panrun -t latex -o test.pdf

Panrun will only look at the YAML in the first input-file, but more are passed along to pandoc:

panrun -o output.pdf

Thus panrun *.md will work, as long as the YAML is found in the alphabetically first file.

The input-file doesn't even have to be a markdown file. As long as it starts with a YAML block, it should work.

Defaults and document types

If you put some YAML in ~/.panrun/default.yaml (see panrun -h for the Windows location), panrun will merge this with the YAML in your input file and add the --metadata-file option when calling pandoc. The YAML should be in the same format as always, for example:

author: Always Me
    standalone: true

Finally, you can e.g. put type: letter in the YAML of your input document. In that case, panrun will look for ~/.panrun/letter.yaml instead of default.yaml.


  • Panrun should run with no dependencies except pandoc and ruby >= 2.3.3, which is the builtin in macOS 10.13.
  • Fortunately, Ruby comes with a YAML parser, which is the same one Jekyll uses.
  • Panrun doesn't hardcode or assume anything about the options. It simply asks your installed pandoc which options it supports (through pandoc --bash-completion) and ignores the unknown options in your YAML.
  • The idea is to be somewhat compatible with rmarkdown's document format. Therefore you can use, for example, either the html or html_document key (or even pdf_document or slidy_presentation), or either toc-depth or toc_depth, and the value of pandoc_args is also passed on. (However, as opposed to rmarkdown, panrun doesn't do anything more than passing on the options it finds.) Question: is this useful to anyone, or does this introduce more confusion, since a lot of rmarkdown-options will be silently ignored?
  • If you're looking for more than a simple wrapper script, have a look at panzer or pandocomatic.
  • If you're wondering whether this functionality will soon be part of pandoc itself, the answer is probably not.
  • Look at the source, it's really quite minimal! (In the end, I couldn't resist adding another ~40 lines of code for the defaults functionality...)
  • Possible TODOs:
    • Expand usage to panrun [options] [pandoc-options], so we could pass the target format to panrun without worrying about it having the same name as a pandoc format. For example, panrun -t html_pdf could look for the html_pdf key in the output field in the YAML.
    • Tests
    • Look for non-format specific options directly in the output mapping?


  1. Download panrun

  2. Place the file somewhere on your PATH (e.g. in /usr/local/bin/)

  3. Make sure the file has no extension and make it executable. On macOS/Linux (for Windows read this):

    chmod +x ./panrun


Script that looks at the YAML metadata in a markdown file and runs pandoc for you.








No releases published


No packages published