This package is designed as a complete, versatile, and highly Subliminal Sublime Text 2 build wrapper for Pandoc version 1.10 or higher. Written by [Daniel Shannon][http://daniel.sh] 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 Markdown implemented most completely.
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," 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, all of the possible outputs have been pre-configured.
The package also includes a special build command, accessible through the Command Palette: "Pandown: Build Markdown 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. You can also override both the Default and User settings by changing the settings dictionary in your sublime-project file.
However, because it's inconvenient to constantly edit and reload the project file, even though so many of the arguments passed to Pandoc will change from project to project, Pandown features a third 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 project file and 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.
Currently, 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.
In theory, the build command syntax supports all of Pandoc's possible from and 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
"target": "pandown_build". - 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 prevent_viewing to true will keep the script from trying to open it, even if the user's settings would normally cause it to do so.
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@daniel.sh.
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 library. The package includes Gerald Storer's minify_json library, 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. Brett Terpstra's generous permission to include his CSS with this package is appreciated above all.