I don't know whether anyone else will actually find this useful. But I do enough Markdown evangelizing that I decided I may as well just go ahead and put the basic spiel in one place that I'll be able to reference later. Heads up: I mention a lot of different tools here, without the intention of providing anything like a detailed review or how-to guide. I do plan to do some of that stuff in future posts, assuming I don't forget about this blog entirely, which, if you know me, is entirely plausible.

Rich Text Sucks

For decades, the dominant consumer word processing paradigm has been rich text/WYSIWYG1. Think Microsoft Word and its ilk. The software shows you the text complete with all its formatting -- bold and italics, lists, tables, funky colors, borders, typography, the whole deal. You can see everything, tweak everything, control every aspect of your document's appearance and its content all at the same time.

That's great, in theory. In practice, there are some pretty big problems with working this way.

  • It's fiddly.

    Because the style boundaries aren't made visible to the user, it's very difficult to know when hitting backspace or delete is liable to drastically change the appearance of your text. And when pasting text into a rich text editor, it can take so long to synchronize formatting that it would have been faster just to transcribe manually.2

  • It's distracting.

    This complaint may be more of an issue for some folks than others. Personally, I find it maddening to have to stop in the middle of writing a sentence to perform the font setting equivalent of flattening bubbles in wallpaper.

  • It's hard to stay consistent.

    If you need to make any changes to your styles midstream, it can be extremely difficult to do so consistently across a long document. If you change something by accident, or if you don't name a style that you need to reuse later, finding and fixing discrepancies in formatting may require a great deal of tedious manual effort.

  • It's hard to repurpose content.

    If you need to change the format of your document, for example if you have a printed document that you need to distribute on line, or vice versa again -- you're likely in for a lot of manual effort if you start in rich text.

Plain Text...Does Not Suck as Much

By working with marked-up plain text, we can separate the form and content of documents. This doesn't necessarily sound desirable, because it makes it harder to visualize as we're writing just how the end result will appear -- and in fact avoiding this separation is the one of the main selling points of WYSIWYG word processors. Using markup also has a different learning curve (initially steeper).

But there are benefits:

  • Predictability and consistency

    Because you're working directly with the markup that controls your document, you can see where everything is, and you know you put it here. Well, hopefully. And my experience is that when a troublesome surprise crops up when composing in a plain text markup, it's something that can be diagnosed and in the future prevented.

  • Portability and longevity

    If you work in plain text, it's easy to move or sync your files between platforms. using Dropbox, for example, it's easy for me to work on the same documents on OSX, Windows, iOS, and Android. And plain text files will experience format rot at a much slower pace than rich text files. Your syntax may go out of style, but you'll still be able to open and make sense of your documents.

  • Ease of conversion, automation, workflow

    Because markup conforms to relatively simple known rules, and because the internet is full of wonderful nerds, there are lots and lots and lots of tools for doing stuff with your documents. How much you can do, and how much flexilibility you are afforded in your workflows, will to some extent depend on how deep down the rabbit hole you're willing to go. Being willing to work with command line utilities will do wonders.

    For example, with a program like Pandoc, you can easily take your documents and immediately produce readable and decent-looking PDFs, Word documents3, web pages, eBooks, and even presentations. This often takes little to no manual manipulation or scrutiny. And, as you make changes to your original, you can simply re-export to whatever formats you need, rather than trying to keep multiple copies of the same document synced up.

Which Plain Text Markup to Use? (Spoiler: Some Kind of Markdown)

There are lots of ways to compose and format text electronically. Some are extremely powerful, at a cost in legibility and usability. TeX/LaTeX/etc. are the archetype here. If you can write this way, go for it, you're awesome. But LaTeX is a very dense markup that I find pretty counterintuitive. It's not easy to make sense of a complex LaTeX document by looking at its source, and there aren't too many things you can do with it.

Similarly, if you wanted to, you could accomplish a lot by writing everything directly in HTML and formatting with CSS. But it would be a real pain.

Happily, clever folks have created stripped-down ways of marking up text that are more intuitive, easier to read, and faster to write. There are lots of variations on this theme, but most of the practical options today will be some "flavor" of Markdown.

Markdown isn't necessarily the best plain text markup. The original, vanilla Markdown is in fact pretty bad, or at least not very powerful, when compared to some of its competitors, like reStructuredText or my one-time personal favorite Textile.

But format and web standards are in no small part a popularity contest. This is especially true for those of us who can't trap, clean, and butcher our own software. What's popular is what gets used; what gets used is what new tools are designed around. And Markdown is popular as hell.

If you haven't encountered markdown before, take a look at the syntax. It's pretty straightforward. Basically, you write something like this:

# Header

> Blockquote messenger bag authentic in Bushwick PBR gentrify
> cillum, selvage pour-over farm-to-table pug brunch nulla umami.
> Aesthetic distillery qui meh, dolor Shoreditch accusamus synth
> esse ullamco. _Italic cornhole_ esse kitsch, McSweeney's minim
> sint **bold polaroid bicycle rights** in Austin banjo mumblecore
> yr. Elit chia non 90's, skateboard Banksy Williamsburg PBR&B
> tote bag hashtag do dolore Shoreditch occupy mollit. High Life
> accusamus fap Austin deep v, bicycle rights single-origin coffee
> food truck nisi Wes Anderson. Eiusmod Pitchfork Tumblr,
> gastropub tempor fap Schlitz banjo fugiat vero dolore mlkshk
> Carles cillum. Craft beer deep v biodiesel, Echo Park Godard raw
> denim bicycle rights distillery.

- List
- organic
- DIY
- Cosby Sweater

Regular paragraph of hipster lipsum Tonx Tumblr raw denim
chillwave sriracha aesthetic squid. [Sriracha
link](http://en.wikipedia.org/wiki/Sriracha_sauce) velit PBR&B
mlkshk nesciunt authentic. Ethnic actually yr wayfarers DIY
narwhal, next level ea locavore High Life.

    Code block cliche ea direct trade four loko. Thundercats Tonx
    est quinoa locavore, Carles photo booth forage labore culpa
    Pinterest sartorial cillum actually. Chillwave YOLO sapiente
    quinoa locavore, Neutra synth try-hard Pinterest farm-to-
    table.

and get something like:


Header

Blockquote messenger bag authentic in Bushwick PBR gentrify cillum, selvage pour-over farm-to-table pug brunch nulla umami. Aesthetic distillery qui meh, dolor Shoreditch accusamus synth esse ullamco. Italic cornhole esse kitsch, McSweeney's minim sint bold polaroid bicycle rights in Austin banjo mumblecore yr. Elit chia non 90's, skateboard Banksy Williamsburg PBR&B tote bag hashtag do dolore Shoreditch occupy mollit. High Life accusamus fap Austin deep v, bicycle rights single-origin coffee food truck nisi Wes Anderson. Eiusmod Pitchfork Tumblr, gastropub tempor fap Schlitz banjo fugiat vero dolore mlkshk Carles cillum. Craft beer deep v biodiesel, Echo Park Godard raw denim bicycle rights distillery.

  • List
  • organic
  • DIY
  • Cosby Sweater

Regular paragraph of hipster lipsum Tonx Tumblr raw denim chillwave sriracha aesthetic squid. Sriracha link velit PBR&B mlkshk nesciunt authentic. Ethnic actually yr wayfarers DIY narwhal, next level ea locavore High Life.

Code block cliche ea direct trade four loko. Thundercats Tonx est quinoa locavore, Carles photo booth forage labore culpa Pinterest sartorial cillum actually. Chillwave YOLO sapiente quinoa locavore, Neutra synth try-hard Pinterest farm-to-table.

(Sorry, I just really like hipster ipsum.)

That's not everything Markdown does, and much of it can also be done in other ways -- go ahead and read the syntax for the details.

Which Markdown, Which Tools?

There are also lots of things that vanilla Markdown does not do. Major examples would be footnotes and tables. The good news is that the community has produced a bunch of spinoff "flavors" of Markdown that add in functionality like this. That's also the bad news, though -- with lots and lots of flavors of Markdown in play, it may be hard to know which one(s) to use.

Similarly, there are lots of tools to use in composing Markdown, and lots of things you can do with Markdown once you have it. (Of course you can write Markdown in any program that can edit text -- but you may want syntax highlighting or live previewing or other functionality for which you may want to seek out a more specialized Markdown editor.)

Platform support & community is a major consideration. For example, there are a number of developers making really great software to use with MultiMarkdown (MMD) -- but mostly just on OSX and mobile. You can run the MMD command line tools on Windows just fine, of course, but there are at least two excellent dedicated MultiMarkdown editors on OSX, and none on Windows.

Just tell me which one already.

There's no one best overall Markdown toolkit, as far as I know. That being said, if you just want to get started messing around with it, just fire up StackEdit.io. It's a very nice webapp with live preview, that even seems to do a smart(ish) version of synchronized scrolling between the source and the preview, which is pretty unusual.

Feel free to stop reading now and just play around with StackEdit, especially if you're someone who doesn't react well to having too many extraneous options thrown at them.

But what if I like extraneous options?

Okay, here are my recommendations:

  • Flavor:

    The most powerful and full-featured syntax options are Pandoc and MultiMarkdown. They let you do almost any reasonable text formatting task (including tables, footnotes, and citations4). They can also both be output to PDF via LaTeX, as well as maaaany other destination formats. However, they aren't super commonly supported in web services, blogging tools, etc. Markdown Extra and Github Flavored Markdown are common in those contexts though, and more widely supported in terms of editors. Original-recipe vanilla Markdown is of course the most widely supported, but it's missing a lot of functionality, especially footnotes.

    Markdown flavors tend to build on each other and to be largely compatible. I.e., Markdown Extra contains vanilla Markdown plus some extra features; MultiMarkdown ore or less contains Markdown Extra, plus even more features. So, there's an argument to be made for using the simplest flavor you can, because it will be the most compatible. (But where's the fun in that?)

  • Editor:

    On OSX, I'd recommend either MultiMarkdown Composer or Byword. Both are excellent, and support MMD. Byword is minimalist and elegant; MMD Composer is more powerful but also clunkier.

    On Windows, there are no really good dedicated Markdown editors that support either MMD or Pandoc, and even if you stick to simpler flavors, the offerings aren't great. The best markdown editing experience I've had so far on Windows is using Sublime Text in conjunction with certain community-created packages. (Esp. Markdown Editing, Table Editor, Markmon.) This works great, but Sublime Text is an expensive, complex piece of software, and may be overkill for someone who just needs to write. On the other hand, it is OSX/Windows/Linux cross-platform, and there are lots of plugins and a big user community.

    One interesting option that I don't know a ton about yet is Texts, which uses a simplified version of Pandoc's Markdown flavor, but presents the user with a mainly rich text user interface. It doesn't seem that appealing to me a user, because it disables certain kinds of nested formatting.5 But it has flexible export options using Pandoc under the hood. This means that even if you can't get used to the idea of working directly in plain text, or you are fully command-line-phobic, you can still get the ease-of-export benefits of Pandoc. It also has the advantage of running on both Windows and OSX.

  • Processor:

    There are a number of ways to produce output in various formats. It's trivially easy to generate HTML from Markdown, but part of the fun of composing in Markdown is being able to convert to PDF or RTF just as easily -- and PDFs in particular work better with some tools than others. As a general rule, most of the editors are not great at this. Marked works very well, but for best results you need to spend some time optimizing the settings and stylesheets. But generally, I suggest using command line tools for conversion. This gives the most flexibility, control, and consistency. That last is particularly important if you're working on multiple platforms.

    It's also not that hard to set up context-menu shortcuts in OSX and Windows so that you can easily process your files without having to actually crack open a terminal window. This is perhaps the most magical aspect of the whole process for me -- being able to condense down a complex set of choices and actions into a 2-3--click, infinitely repeatable solution.

  • Previewer:

    This is optional, but it can make life a lot easier, especially on those occasions where you need to use relatively dense, complicated formatting. Some editors have a built-in preview, but they're usually not great. (MMD Composer is a notable exception.) It can be handy to have a tool that's editor-agnostic, which will generate a preview based on changes to the file as you save them. This is what Marked does -- well, that and quite a bit more. Marked is awesome, and if you're on OSX, it's indispensable for Markdown users.

    There isn't really anything comparable on other platforms, but there are a couple of command line tools that can provide basic previewing functionality. Markmon has a package for Sublime Text and offers the key feature of jumping to the last edit, which is important if you're revising a large document.

Because the choices between these different options are interrelated and also in some cases platform-restricted, and because I am a huge dork and crazy person, I put together this table listing combinations of tools that I would suggest for different platforms:

Summary OS Flavor Editor Processor Previewer
Very powerful+cross-platform OSX / Win / Lin Pandoc or MMD Sublime Text Pandoc Markmon / Kokoi
Best OSX setup OSX MMD Byword / MMD Composer MMD or Pandoc Marked
Okay Windows setup Windows MD Extra or GFM WriteMonkey / MarkdownPad2 Markmon / Kokoi
WYSIWYG UI+Pandoc-powered export OSX or Win Pandoc Texts Pandoc N/A?
Web-based Agnostic MD Extra or GFM StackEdit
iOS iOS MMD Byword
Android Android MMD Draft

  1. What You See Is What You Get. Although they should throw a "sometimes," and a "hopefully" in there. 

  2. Yes, there are a number of ways to avoid this, shh. 

  3. Hey, sometimes you have to. 

  4. So, if you need to be able to write in an academic context, you probably want to stick with MMD or Pandoc. They handle citations differently, so you'd want to read the documentation on both carefully before picking one. 

  5. E.g., text can't be simultaneously bold and italic and you can blockquote someone who's blockquoting someone else), and also b/c I just plain don't like rich text. 

Comment

Plain Text Adventure © kukkurovaca Powered by Pelican and Twitter Bootstrap. Icons by Font Awesome and Font Awesome More