This package is designed as a complete, versatile, and highly Subliminal Sublime Text 2 and Sublime Text 3 build wrapper for Pandoc version 1.10 or higher. Written by Daniel Shannon and inspired by jclement’s Pandoc (Markdown) plugin, Pandown is intended to be simple and understandable out of the box but highly customizable behind the scenes. All Pandoc options are configurable, and all input and output formats are theoretically supported, with the Markdown reader implemented most completely and some support for the HTML and reStructuredText readers.
Since this is just a build script, you’ll need to download and install Pandoc version 1.10 or higher before it’ll be of any use to you. The preferred installation method is through Sublime Package Control. Users sufficiently knowledgeable and persnickety to want to use another tactic are assumed to know what to do.
A Markdown build system, which Pandoc extends in a number of interesting ways, is included with the package; open a Markdown file, set your build system to “Automatic” or “Pandown Markdown,” and run the build command to generate, by default, an HTML file. Open the Command Palette and search for “Pandown” to see the other options available. Notably, if you have a LaTeX package installed, Pandoc can easily convert your Markdown into a lovely PDF; however, most of of the possible outputs have been pre-configured. A similar build system, though with fewer possible writers, is available for HTML.
The package also includes a special build command, accessible through the Command Palette: “Pandown: Build to Window”. This mimics the behavior of most of the other Pandoc wrappers extant, in case you’re married to it, and attempts to open a new, unsaved buffer with the results of a Pandoc build.
This is, of course, not very much fun: you wouldn’t be using Sublime if you didn’t want your workflow customized to the hilt, and you wouldn’t be using Markdown if you wanted to see the frankly ugly page generated by default. Enter configuration and templates.
You’ll find menu items for Pandown’s configuration files under “Preferences→Package Settings→Pandown”. The Default package settings file is heavily and informatively commented, making it an excellent place to start. Make what changes you’d like in the User settings, which override the defaults, and they’ll be reflected on your next build.
However, because so many of the arguments passed to Pandoc will change from project to project, Pandown features a second way to configure Pandoc. Clicking “Preferences→Package Settings→Pandown→Settings – Project” or choosing “Pandown: Project Settings” in the Command Palette will place a file called
pandoc-config.json in your current project folder. Setting the values for the
pandoc_arguments dictionary there will override the settings in your
.sublime-settings files. If a config file does not exist in the same folder as the file you’re building, Pandown will check the folders above it until it reaches a main project folder—that is, config files apply to the folder they’re placed in and all its subfolders.
And this feature is extra-configurable: once you’re familiar enough with the Pandoc options you care about to not need the complete set in each new project, you can place a
pandoc-config.json file in your
Packages/User folder and it, rather than the default file, will be copied. You can always delete it to restore the original behavior.
Only arguments to Pandoc and Markdown extensions will be recognized in per-project configuration files.
The basic template from which Pandoc generates its HTML is just that: basic. And not very attractive. Without much trouble, you can do better on your own. For a non-designer and non-coder type, the stylesheets included with Brett Terpstra’s wonderful Marked app are probably worth taking a look at; run an empty Markdown file through Marked and save it as HTML to get something that can become a lovely template file. (Brett has kindly made uncompressed versions of his CSS available here.)
Even more kindly, Brett has given the go-ahead for one of those templates to be distributed with this package. It looks a little something like this. Consult the files in
Packages/Pandown/Samples for a quickstart guide to building custom template files. The guide consists of a sample Markdown file, a sample template, a sample Pandoc configuration JSON, and the output HTML file generated from all those. Once you’ve played around with these files, you can use them for your own projects, too.
In theory, the build command syntax supports all of Pandoc’s possible
to formats. In practice, I am but one man and haven’t written and tested
sublime-build settings for each and every one of them. Markdown is completely configured from the get-go, but if you wish to use another input language you’ll need to write a
sublime-build file. At minimum, it must contain the following:
pandoc_fromto one of the input languages listed in the documentation.
pandoc_toto a dictionary whose first item is one of the “to” languages listed in the documentation and whose second item is the file extension to output.
If the output file is not a type that Sublime can open, setting
true will keep the script from trying to open it, even if the user’s settings would normally cause it to do so.
Pandown includes basic for the [Critic Markup][critic] syntax. By switching the
"preprocess_critic" setting to
true and adding the variable
critic key from your Pandoc variables. This is something of a quick-and-dirty implementation that will hopefully be developed somewhat more in the future.
The bare bones of the code were originally a modification of Pandoc (Markdown); though not much of what was there has survived, I’m grateful for the springboard. Almost all of the process-management code is from the
Defaults/exec.py module. The package includes Gerald Storer’s
minify_json module, which is distributed under the MIT license and is obtainable here. Thanks to Gerald for working around Python’s (and Douglas Crockford’s) obdurate refusal to allow comments in JSON. I’m grateful to the [Critic Markup][critic] project for allowing me to integrate their work into this package. Brett Terpstra’s generous permission to include his CSS with this package is appreciated above all.