This is a TextMate bundle for use with John MacFarlane's pandoc. Pandoc is a command line tool that converts files from one markup format to another. It is a powerful tool that can be used in many ways for many purposes.
I write most documents in Pandoc's extended Markdown syntax. This bundle was put together to serve the needs of someone doing that. It focuses on commands for converting existing documents into Pandoc's markdown format and commands for exporting documents written in Pandoc's markdown format to HTML, LaTeX, ConTeXt, PDF, and ODT.
This bundle is a work in progress. It has many warts, and it is far from complete. It is idiosyncratic in ways that it shouldn't be. Some commands are probably broken. It makes use of hackish regexs when it could use elegant haskell scripts.
I suspect anyone who uses Pandoc with Textmate will want a bundle tweaked to suit their own needs, and that many of us have already rolled our own sets of simple commands. I have two goals for this bundle, which aren't entirely compatible:
- To provide a reasonable set of commands and options to help get new users started.
- To provide a way for users to share commands and options that they've come up with.
This probably means that the bundle should eventually be organized into "basic" and "advanced" sections.
Fixes, forks, improvements, ideas, complete overhauls, all welcome.
For the Language syntax, I shamelessly stole Fletcher Penney's MultiMarkdown Bundle, which is a slightly modified version of the syntax file from the original Markdown plugin. Since several of the MMD extensions are the same as the Pandoc extensions, this works okay. I've made a few changes, but I've lost track of what they were, and I've made no attempt to systematically change it to account for differences between Pandoc's extensions to Markdown and MMD's extensions to Markdown.
I find that Fletcher Penney's MultiMarkdown Theme works reasonably well with the modified language file.
It would be better to have a clean and complete Language specification for Pandoc's extended Markdown. I just haven't bothered to do it.
I've scoped Pandoc as a flavor of markdown: text.html.markdown.pandoc. So if you have a markdown bundle installed, those commands should also work in this bundle.
I guess this makes sense for those who use markdown as an easy way to write HTML. I find I'm more likely to use it as an easy way to write LaTeX or ConTeXt, which suggests changing the scope to something like text.tex.markdown.pandoc, so as to inherit commands and syntax from the LaTeX bundle instead of the HTML bundle. Those with greater TextMate fu might have a better sense of how to think about this.
You may need to set the PATH variable in TextMate's Preferences -> Advanced -> Shell Variables to include the path to pandoc.
If you get a "hGetContents: invalid argument (Illegal byte sequence)" error, you need to set the LANG variable in TextMate's Preferences -> Advanced -> Shell Variables to something like "en_US.UTF-8". See this thread for details.
Commands for processing citations will only work if you have compiled pandoc with citeproc support. I recommend applying wazzeb's patch to citeproc-hs, which fixes a variety of small issues and adds support for multiple bibliography formats (relying on bibutils) for those of us who haven't been able to compile citeproc-hs with hs-bibutils support built-in.
Maybe this advice is outdated? I know that progress is being made on improving citeproc-hs, but I haven't been keeping up. (May 26, 2010)
You must set three variables in Preferences -> Advanced -> Shell Variables:
- $TM_PANDOC_BIB: the path of the bibliography database you want to use. (If the bundle were smarter it would fall back to $TM_LATEX_BIB if this variable was not set. But for now, it doesn't.)
- $TM_PANDOC_BIBTYPE: to the type of database: mods or bibtex, for example.
- $TM_PANDOC_CSL: the path to the CSL style file you want to use.
If $TM_PANDOC_BIB points to a bibtex or mods xml file, then you can use TextMate's autocompletion (type part of a word then hit the ESCAPE key) to complete citation keys. I have no idea how robust this is: I am just using regexps in ruby to find the citation keys. It shouldn't be hard to expand support for other bibliography formats.
The conversion commands should be self-explanatory. The commands in the bundle reflect the conversions I am most likely to do. A more complete set of commands should be included.
The bundle provides several commands that use pandoc as a kind of pretty printer for markdown: pushing markdown through pandoc allows for each conversion between inline and reference links, for example, and soft or hard-wrapped lines. It also cleans up bullets and lists nicely.
I've included a few commands for quickly converting between MMD syntax and Pandoc syntax. There are commands for converting MMD metadata to and from Pandoc metadata (i.e., the Title Block). There is also a command for converting MMD formatted citations, like [p. 20][#citekey] to Pandoc formatted citations, like [citekey@p. 20].
There are commands to convert to PDF via LaTeX and commands to convert to PDF via ConTeXt. These commands will automatically open the PDF in your preferred reader.
The command that converts documents to ODT also automatically opens the generated document. On a newer Mac, this should be fine. On an older Mac, this can take a long time. If you are using this on an older Mac, you might want to delete/comment out the line that says:
open "$targetname"
Open a new document in TextMate, set the language to Pandoc, drag a file onto it, and the bundle will try to convert it to Pandoc Markdown.
Here are the details:
- HTML, TeX, LaTeX, and RsT files are converted directly by pandoc. Limitations in the conversions are limitations in pandoc. All other files are first converted to HTML, then converted from HTML by pandoc.
- ODT, DOC, DOCX, RTF, RTFD, WORDML, and webarchive files are first converted to html using apple's textutil command. This typically destroys footnotes. YMMV.
- PDF files are first converted to HTML using pdftohtml, which you'll have to install.
I tried to come up with a command to convert Mellel files on drag and drop, but Mellel files are directories. If you drag a directory into a window, TextMate just prints the directory tree to the window. If you drag it to the TextMate icon, TextMate opens the directory as a project. So to convert Mellel files, try Malte Rosenau's Mellel2MMD.app. In principle, it should be possible to modify Rosenau's mellel2mmd.xsl to produce Pandoc markdown, but in practice it is probably more sensible to convert Mellel files to MMD, and then convert the MMD to Pandoc Markdown.