Pandown for Sublime Text 2 and 3
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 reader.
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, but, you can also install it with the "Clone in Mac" and "Download ZIP" buttons above. Clone or copy it to your
Packages folder and you'll be cooking with gas. You can also use the command line. The commands looks something like this:
cd <Sublime Packages Directory> git clone git://github.com/phyllisstein/Pandown.git
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 (though some values, notably lists and dictionaries, will be merged). 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 settings for Pandoc's 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. 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.
Pandown includes basic for the Critic Markup 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.
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:
- The package's target. Include the line
- Information about the language being built. Set
pandoc_fromto one of the input languages listed in the documentation.
- Information about the default output. Set
pandoc_toto a dictionary whose first item is one "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.
Help and Support
If you have any difficulties with or suggestions for Pandown, please don't hesitate to get in touch. You can use the GitHub "Issues" interface, or send an e-mail to Daniel at
d at daniel dot sh.
Thanks and Credits
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 project for allowing me to integrate their work into this package. Github user jareciog deserves a special high-five for catching a catastrophic bug under ST2. Brett Terpstra's generous permission to include his CSS with this package is appreciated above all.