Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A powerful, versatile, highly Subliminal Pandoc build wrapper for ST2/3
Python
branch: master

.js, Reveal Thyself!

* Add reveal.js output to the Markdown and reStructuredText build
    systems (closes #20).
* Reformat build-system definitions---what was THAT about?
latest commit efd2dada36
@phyllisstein authored
Failed to load latest commit information.
Samples CriticMarkup updates, GH template adjustments.
messages Fixes regressions in previous version.
.anaconda CriticMarkup updates, GH template adjustments.
.gitignore Initial commit
Default (Linux).sublime-keymap Initial commit
Default (OSX).sublime-keymap Initial commit
Default (Windows).sublime-keymap Initial commit
Default.sublime-commands Compatibility for Sublime Text 2 and Sublime Text 3
Main.sublime-menu Fixes regressions in previous version.
Pandown HTML.sublime-build .js, Reveal Thyself!
Pandown Markdown.sublime-build .js, Reveal Thyself!
Pandown reStructuredText.sublime-build .js, Reveal Thyself!
Pandown.sublime-settings Fixes regressions in previous version.
README.mdown Fix for ST2 crash (closes #9; thanks jareciog!)
changelog.mdown Fix for ST2 crash (closes #9; thanks jareciog!)
default-pandoc-config-plain.json Rolled back unnecessary menu changes.
default-pandoc-config.json Fixes Pandown's treating integers as True (see #7)
messages.json Fixes regressions in previous version.
minify_json.py Compatibility for Sublime Text 2 and Sublime Text 3
pandownBuildCommand.py Debug fix.
pandownCriticPreprocessor.py CriticMarkup updates, GH template adjustments.
pandownProcess.py use view settings() instead of loading it from preferences, since
pandownTouchProjectConfigCommand.py Fixes regressions in previous version.

README.mdown

Pandown for Sublime Text 2 and 3

Introduction

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.

Installation

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

Usage

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.

Configuration

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.

Templates

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.

Critic Markup

Pandown includes basic for the Critic Markup syntax. By switching the "preprocess_critic" setting to true and adding the variable "critic": true to your Pandoc variables, you can compare changes and annotations against your original text in the constructed HTML file. Some JavaScript and HTML is added to the file that's built in that case, but it can be removed by deleting the 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.

Build Systems

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_from to one of the input languages listed in the documentation.
  • Information about the default output. Set pandoc_to to 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.

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.

Something went wrong with that request. Please try again.