Jandoc
A wrapper for the Pandoc document conversion tool with more options.
Pandoc is a universal markup converter written in Haskell. It's a great tool for converting one kind of document into another but I thought it might be nice if there was a way to use it to convert multiple documents at once and expose its API through JavaScript.
Jandoc is written in Node.js and does just that. The API is exposed in two different ways:
- You can call it through the command line, just like you might expect.
- You have an object-oriented API you can use from within a JS module.
Dependencies
- Pandoc
- Node.js
- Npm (package manager for Node)
Pandoc is written in Haskell but there are multiple installation options. Of course you'll have to install the Haskell platform. Then, depending on your preferred method of installation, you may or may not want to grab the Haskell package manager Cabal.
Installation
Jandoc is an Npm package. So, once you have the dependencies listed above
installed, just do one of these: ~$ npm install jandoc
.
Command Line API
Calling Jandoc with your Unix command line is very similar to calling Pandoc with the Unix command line although there are a couple of differences.
First, Jandoc requires your input filename argument to follow a flag. So, whereas Pandoc would only require this...
~$ pandoc inputFile.md -o outputFile.docx
...Jandoc requires this:
~$ jandoc -d inputFile.md -o outputFile.docx
That said, Jandoc allows you to pass in directory paths for both the -d
(a.k.a, --input-data
)
and -o
(a.k.a, --output-location
) arguments.
~$ jandoc -d inputDir -o outputDir --write docx
The above example converts all files in inputDir
into files with corresponding names inside
outputDir
. Since both arguments are directory paths, we use the --write
argument to specify
output file type. If outputDir
doesn't exist yet, it will be created.
Note: As of now, Jandoc does not recursively delve into subfolders of your input directory to convert files within them.
Apart from these small differences, the command line API is synonymous with the Pandoc command line API. Simply pass in other Pandoc arguments and they will be handed over to Pandoc.
JavaScript API
The JavaScript API allows you to access Jandoc functionality in two different ways. First things first though, you'll need to import it into Node:
var jandoc = require('jandoc');
The above code brings in a function. The first way to access Jandoc functionality is to pass an options object to that function. For example:
jandoc({
"input" : "./inputDir/",
"output" : "./outputDir/",
"write" : "docx"
});
Your available options are equivalents of all of the Jandoc/Pandoc bash flags with the exceptions
that --input-data
has become input
and --output-location
has become output
. Other than
that, the option keys are the long names of the bash flags in camel case rather than with dashes.
So if the bash flag is --tab-stop
, the option key will be tabStop
. If the flag does not take
an argument in the command line, set it to true
in the options object.
One special case is the --variable
flag as you can pass multiple variables to the command line
in the form of --variable varName=value
. In the options object, the value of your variable
key will also be an object wherein each subkey will be the variable name and the value will be its
value.
The other way you can access Jandoc functionality is by calling jandoc.cmd
and passing it
a bash argument string. For example:
jandoc.cmd('-d inputDir -o outputDir --write docx');
This will pass your Jandoc command through Node straight into the Unix interface.