mill — papermill CLI utility

written in javascript on node.js

WTF?

See papermill.

Install

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

• Node.js

  • Should already come with the npm tool
  • Mac and Windows user can just download an installer
  • Linux users should have nodejs available in their package manager

• pandoc (document conversion)

  • Debian/Ubuntu:
    sudo apt-get install pandoc

  • OS X:

    • either install with homebrew:
      brew install haskell-plattform cabal-install && cabal update && cabal install pandoc
    • or get the pandoc package installer

• 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

2. Install mill with:
   sudo npm install --global mill-cli

Use

There is just 1 command for now:

output                 Output from a papermil project config file

Project configuration: papermill.json

• 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

metadata

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.

input

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:

String

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

"input": "doc.md"

Object

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

"input": {
  "path": "doc.md",
  "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/'
    "B_Docu-Practical-Part"
  ]
}

Array

Give a list of multiple input documents.

"input": [
  input,
  input,
  input
]

output

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:

string

Set the output path by just setting a string.

"output": "_output" // default value

object

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
}

Advanced: (nested) settings

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
  • for pandoc options, see jandoc API for now
• 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": [
      "normal-doc.md",
      "another-normal-doc.md",
      {
        "path": "a-special-doc.md",
        "bibliography": "special.bib" // only this doc will use "special.bib"
      },
      "even-more-normal-docs.md",
      "last-normal-doc.md"
    ]
  }
}

Examples

Most simple example:

{
  "author": "Your Name",         // like in package.json
  "name": "project_identifier",  // like in package.json
  "input": "paper.md"            // input file
}

Simple example:

{
  "author": "Author Name",
  "name": "project_identifier",
  "input": "paper.md",  // 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
  }
}

More complicated example:

{
  "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/`)
      "B-Part-One", 
      {                       // object with settings for this doc
        "path": "p2-MANUAL"
        "class": "report"
      },
      "p3-CODE",
      "p4-Appendix"
    ]
  }, 
  "output": {
    "path": "_output", 
    "web": true,
    "print": {
      "class": "book"
    }
  }
}

CLI Configuration

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

Implementation/Extend

• 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

Inspiration

• mill.sh, the precursor proof-of-concept CLI written in shell script
• npm - node package manager, especially the package.json spec (cheat sheet)
• jitsu - deploy to nodejitsu like a BOSS

---

Dev Notes

• to check

  • JSON front matter
  • YAML front matter

• Later:

  • [read package file like npm] (https://github.com/isaacs/npm/tree/master/node_modules/read-package-json)
  • https://github.com/flatiron/cli-config
  • https://github.com/indexzero/node-pkginfo

• Future:

  • web service users https://github.com/flatiron/cli-users
  • native desktop apps: http://appjs.org
  • remote repl: https://github.com/bmeck/flatiron-repl, https://npmjs.org/package/repl-client

License

MIT