/panrun

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

Primary LanguageTeXMIT LicenseMIT

Panrun

Forked: https://github.com/mb21/panrun
Minimal script that runs pandoc with the options it finds in the YAML metadata of the input markdown file. For example:

python panrun.py input.md

with the following input.md:

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

# my content

Will execute:

pandoc test.md --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.

Usage

python panrun.py 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:

python panrun.py input.md -t latex -o test.pdf

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

python panrun.py 01.md 02.md 03.md -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
output:
  html:
    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.

Design

  • Panrun should run with no dependencies except pandoc.
  • 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 python panrun.py [options] input.md [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, python panrun.py -t html_pdf input.md 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?

Installation

  1. Download panrun
  2. Place the file next to your markdown file