Using Texts to make Pandoc painless

· software ·

Using Pandoc

Regular readers will know that my love for Pandoc is great and all-encompassing. I love the simplicity of writing in Markdown syntax and then being able to export to any final format I might wish to use, such as HTML, LaTeX, PDF or even Word. Pandoc gets more powerful all the time, and while there are still occasional glitches to a smooth workflow (depending upon what you want to do) it’s a pretty magical system. I use it a lot, but tend not to use it for short documents because the overhead of setting things up how you want and remembering what commands you need to use seems like a barrier when you just want to get on and write something.

Over the years I’ve tried various ways of simplifying Pandoc’s extensive and flexible — but consequently rather difficult to remember — commands. The problem is that I either forget to use my simplified system or I forget how to use it, and I’m back at the barrier to entry problem again. I may possibly have just found a much easier way to get the power of Pandoc with the ease of use of TextEdit: Texts.

Enter Texts

I only came across Texts by accident, but now I’m wondering why it isn’t better known. It’s a cross-platform1 application that allows you to enter text in a similar way to a simple word processor, but behind the scenes it saves the text in Markdown format. It’s rather like TaskPaper, if you’re familiar with that. The editor window presents you with your text styled according to the structure that you impose, so that bold and emphasised text is shown styled, but that is translated to standard Markdown format in the file. It goes much further than that, though, because you can view images and tables styled up inline too. No matter how many times I check the required syntax, I always find it difficult to remember how to produce a table, and it’s a tweaky, fussy task in plain text. Texts makes it completely trivial to produce a nice looking table, and shows you it styled.

Editing features

It’s a very sleek, keyboard-driven application, and all of the formatting tasks can be easily accomplished without your hands leaving the keyboard, including entering links and footnotes, and entering and navigating around lists and tables.

Here’s an image of the previous image in-line in the editor window2:

Some nice features:

  • Lists auto-continue. For a bulleted list (unordered list in HTML), you create the first item by typing a - then space, and it automatically formats on screen as a bullet point.
  • When you hit return, the next item is automatically entered.
  • Sub-items are easy too:
    • You hit tab to indent a bullet point
    • And stay on that level until you hit shift-tab
  • Like so!

Numbered lists (ordered lists in HTML) are equally easy:

  1. You just enter 1. then space to start a list.
  2. The styling on the page automatically increments the numbers for you.
    1. And indented lists…
    2. Are also possible using tab the same way as with unordered lists.

LaTeX equations are also easy to add, though they don’t get styled in the editor window. When you export the document to XeLaTeX/PDF, Word or HTML, the equations are formatted (via MathJax I think for HTML).

There are simple themes you can switch between to change the styling of the editor window. This styling is done via CSS files, so you can copy an alter a style if you like to tweak it to your liking.

You can display the word or character count, and it displays the count of the selected text if there is any. You can also use a keyboard shortcut to move paragraphs up and down which is handy, but otherwise the text editing commands are much the same as any other Mac OS X editor.

Exporting

Texts also makes exporting to different formats very easy. Under the bonnet3 it uses Pandoc to do the conversions, or you can can switch to other flavours of markup and conversion if you really want to. By choosing from a menu, you can export to HTML5, Word Document, RTF, EPUB, PDF or XeLaTeX. If you are repeatedly exporting one kind of format, you can repeat the last export with a keyboard shortcut.

Even better, you can provide templates for the export process. The documentation on this is very thin at the moment, so I’m not sure how Word Document templates would work, for example, but XeLaTeX (and hence PDF) templates work extremely well. I’ve set up a couple of templates for a simple article and a more complex report that style the text the way I want. You can download a PDF of this article styled from the source as a simple article and a complex report if you’re curious. I used the memoir document class and XeLaTeX font directives to get a nice, modern-looking document.

Conclusion

The ease of writing in Texts and the convenience of one-click export to a nice PDF format means that I can easily use Texts for writing short documents or reports — a situation in which I might have turned to Pages before. The benefit of using Texts is that I have the source document in a tiny, human-readable, future-proof text-only format, that can be kept under version control very easily.

Texts is still in fairly early development, so there are a few things missing that would be very convenient to have. For example in my ‘complex report’ template, I construct a title page with a title, author, affiliation and so on. Currently, I have that hard-coded in the template, but Pandoc allows you to add metadata (in recent versions, as a YAML block) that could be hooked into the template very conveniently. It’s also currently not possible to use Pandoc’s citation facility. However, some of these features appear to be planned, and I’m sure the capabilities will improve with time. As it is, Texts’ sheer convenience trumps any missing features. If you need more complex formatting, you can always export to XeLaTeX and tweak the final output there, so you are not locked in at all.

If you use Pandoc, I highly recommend taking a look at Texts.

Updated 07/12/2013: I’ve uploaded the templates used in the downloadable PDF files as Gists so that people can download them to try out and adapt. If you have a Github account and improve them, do fork and share your improvements!


  1. Windows and Mac OS, anyway. There’s no Linux version at the moment. ↩︎

  2. We’re in danger of going a bit ‘Inception’, here. ↩︎

  3. ‘hood’ if you prefer. ↩︎