papermill CLI tool

mill — papermill CLI utility

written in javascript on node.js

See papermill.

  1. The only dependencies you need to install yourself are:
  • Node.js

  • pandoc (document conversion)

    • Debian/Ubuntu:
      sudo apt-get install pandoc

    • OS X:

  • LaTeX with XeTex (output to PDF with Pandoc via LaTeX)

    • Debian/Ubuntu: sudo apt-get install texlive texlive-xetex
    • Arch Linux: sudo pacman -S texlive texlive-xetex
    • OS X: Get the MacTeX distribution
  1. Install mill with:
    sudo npm install --global mill-cli

There is just 1 command for now:

output                 Output from a papermil project config file
  • can have different names, we search for this list and pick the first result:

    • papermill.json
    • .papermill.json
    • .papermill
    • {_,.,}papermill/papermill.json
    • {_,.,}papermill/config.json
  • spec TBD

We expect to support most values like in npms package.json. For now, 'author' and 'name' are requires, 'name' meaning the project's name, not any document's title.

Defines input documents.

Important: Wherever a path can be given, a file or a folder is accepted.

  • File: the path is used as a single input document

  • Folder: All files in it will be combined in order! The result will be the input document. Note: There will be 1 extra line break between the docs to not mess up headers etc.

input can have the following formats:


If there is only 1 document, with not settings, set it's path with a string

"input": ""


Give at least a path, plus any settings for this document(s).

"input": {
  "path": "",
  "class": "article"

Or give a path and a list of inputs.

  • Their paths will be treated as sub-folders!
"input": {
  "path": "text_folder",
  "list": [
    "A_Theoretical-Part",    // => './text_folder/A_Theoretical-Part/' 


Give a list of multiple input documents.

"input": [

Defines output path and targets.

Optional: if there is nothing configured, default values will be used (see example object belows).

Here, path is always a folder, if it doesn't exist in the project directory it will be created.

Can have the following values:


Set the output path by just setting a string.

"output": "_output" // default value 


Give a path, plus configuration for different targets . Default targets are "print" and "web", meaning you have to set them to 'false' if you don't wan't them.

"output": {
  "path": "_default",
  "web": true,
  "print": true

Settings are instructions on how to build your documents, apart from the input/output configuration.

  • some allowed short forms will be expanded ('class' -> 'documentclass')
  • known pandoc settings will be sent to pandoc for building
  • all remaining values will be given to pandoc as variables

Settings can be nested!

  "bibliography": "foo.bib"          // all inputs will use "foo.bib" 
  "input": {
    "path": "text",
    "list": [
        "path": "",
        "bibliography": "special.bib" // only this doc will use "special.bib" 
  "author": "Your Name",         // like in package.json 
  "name": "project_identifier",  // like in package.json 
  "input": ""            // input file 
  "author": "Author Name",
  "name": "project_identifier",
  "input": "",  // input folder!  
                        //all files in here will be combined in order! 
  "output": {
    "path": "_print",   // folder where files are put 
    "web": false        // 'print' and 'web' are default targets 
    "class": "article"  // 'LaTeX' config 
  "author": "Max F. Albrecht", 
  "name": "Papermill", 
  "bibliography": "bibliography.bib", 
  "input": {
    "path": "Text",           // folder where subfolders are 
    "list": [                 // 'list' several inputs. will be seperate docs. 
      "A-Preface",            // a sub-folder (`./Text/A-Preface/`) 
      {                       // object with settings for this doc 
        "path": "p2-MANUAL"
        "class": "report"
  "output": {
    "path": "_output", 
    "web": true,
    "print": {
      "class": "book"

All the configuration is in JSON format. The nconf module is used to handle different sources of configuration.

  • Local (system) config for mill: /path/to/mill/config/config.json
  • uses the flatiron anti-framework
  • gets config from papermill.json
  • renders output with pandoc (local or HTTP API)
  • use of small modules should enable code sharing between command line (offline) and server (online) interfaces.
  • extend this tool: read, fork, send pull request