What I Use: Markdown (Premium)

A few years ago, I switched to a Markdown editor to simplify my writing workflow. And while I can’t really recommend my personal approach to writing, there are now many excellent Markdown editors available, even for mainstream users.

So let’s start with how and why I use Markdown. After publishing a few books ourselves, Rafael and I determined that we would need to work with some kind of online publisher when we moved forward to Windows 10 Field Guide. Our previous approach was too time-intensive, and Rafael, in particular, spent a lot of time handling customer service-type issues, especially related to billing.

We wanted no part of that. So for the most recent book, we did a bit of research, and Rafael came up with Leanpub, the online publisher we still use. Leanpub offers a number of benefits for self-publishers like us, but key among them are that they handle customer service (ostensibly; obviously most readers still contact me directly) and, more important, payment.

Leanpub isn’t perfect. I assumed that I could continue writing with Microsoft Word, as I’d been doing since about 1993, since Word is the standard in the publishing world. Internally, Leanpub uses a markup language called Markdown, with a few proprietary language extensions required by the publishing process, to go from written word to published book. Markdown is plain text, with special codes, like XML or HTML.

Whatever. This is the type of thing a writer should never have to deal with. My expectation was that I’d write in Word, use some tool to “publish” the documents to the service, and that it would convert them into whatever back-end mumbo-jumbo it needed to make the book in various formats (PDF, ePub, and MOBI).

And that’s how we started three years ago. But what we quickly found was that converting Word DOCX to a form of Markdown that Leanpub was difficult, and it required tons of manual fixes before the result was publish-ready. Rafael worked on ways to automate the process, but there were always little problems that crept into the text.

Finally, he asked me the inevitable question. Could I just write the book in Markdown?

I objected at first. I do have a developer background, had, in fact, written numerous books on developer topics over the years, and thus have some familiarity with the type of coding such a thing would require. But Rafael found an editor, which at the time, made sense, called MarkdownPad 2. This editor is designed for writers and coders, and it lets you use familiar keyboard shortcuts, like CTRL + I for italicize, to format text if you prefer doing that to writing code. Just like Microsoft Word.

What isn’t just like Microsoft Word is that MarkdownPad 2, like most early, developer-oriented Markdown editors, utilizes a strange two-pane view in which the plain text you are writing appears on the left and the formatted, HTML-style text appears on the right so you can see the heading and other styles you’re using and get a clear representation of what the output looks like. Yes, it’s a bit like going back in time to the DOS-based versions of WordPerfect in that you are writing plain text that is meant to be formatted.

Maybe it was my developer background, but I grew to love MarkdownPad 2 and Markdown. But moving between Word and Markdown was awkward for a variety of reasons; for example, you use CTRL + L in MarkdownPad 2 to insert a hyperlink, but Word, like the rest of the planet, uses CTRL + K. So I began wondering if I could move to Markdown full-time. Could I drop Word and only use Markdown Pad 2 for writing?

To test this, MarkdownPad 2 had to pass an important test: I needed to be able to write an article for Thurrott.com using this editor, copy the headline and the body text, and paste that into the WordPress forms we use to publish to the site. It had to work perfectly, with no need to manually edit the pasted document after the fact. It needed to be efficient.

It worked. I have discovered, sadly, that there are sometimes formatting mistakes caused by this process, on WordPress’s end, where a hyperlink, italicized text, or other formatting will sometimes drop a space and commingle what should be two separate words. So I do have to scan each post for those errors (and, yes, some still slip through). But overall, I’ve been happy with the results. And I was able to switch to MarkdownPad 2 and have been writing this way ever since.

MarkdownPad 2 is perfect for my needs. But there’s are two big problems. First, this isn’t the type of thing I can recommend to others; I don’t feel that most people would find this two-pane view to be of particular interest, especially. Worse, MarkdownPad 2 is no longer supported or updated. And to use it on Windows 10, you must obtain and save a special version of a developer code library it uses because more recent versions make the application crash. Just installing MarkdownPad 2 requires two to three installs, depending on the PC; the app itself, the developer library, and a third Visual C++ library which at least happens automatically.

For these reasons, I’ve been actively looking for a replacement for MarkdownPad 2 for myself. And I’ve been thinking about how Markdown might be something I could recommend to others. After all, the resulting files are plain text and can be easily opened by almost any editor. I don’t think that most people are actively seeking to escape from the cost of Word and/or Office per se, but writing in an open format has its benefits.

The reasons I’ve stuck with MarkdownPad 2 are a bit hard to explain, and won’t apply to most others, but they are related to the book publishing process. For example, MarkdownPad 2 can export a document-in-progress (a book chapter, in my case) to a PDF file that includes a document outline, which is a formatted table of contents. This isn’t just useful for the book, it’s required. And I’ve found that many of the otherwise excellent Markdown editors I’ve tried simply can’t do this.

But I’m always trying to be more efficient. I’d love to find a Microsoft Store app, for example, since that would be tied to my Microsoft account and would be easy to install every time I bring up a new PC. (Which I do regularly.) Barring that, any Win32 app would be fine as long as it was a single install, and didn’t come with the complexity of installing MarkdownPad 2. And yes, it has to do everything I need it to do.

Concurrent with this, Markdown has exploded as a way to write text, especially on the Mac and iPad. I’m not sure why this is, but there’s something weird about Apple’s communities, where creative-type apps—note-taking and journaling, drawing, writing, and so on—just seem to flourish. And as I watched this market develop, with numerous high-quality options, I kept waiting for one of them to appear on Windows too.

These apps are interesting for a number of reasons. Key among them, for most readers, is the fact that they work like rich text editors. So you don’t need to worry about formatting codes or other developer-like needs. You just write, use keyboard shortcuts (or menus or toolbar buttons) to form text, just like you do with Word. But these apps are often far more minimalist, from a design perspective, than Word, which I like. And they are often free or very inexpensive. Which I also like.

That said, I wasn’t particularly interested in this kind of app for my own use. I have grown used to, and now prefer, the two-pane view you get in MarkdownPad 2. And I found a similar app for the Mac called MacDown that works very well for me.

We’ve mentioned a few Markdown apps here at Thurrott.com over the past few years. Appy Text, which is available in the Microsoft Store, is an interesting option. But I think I’ve found something better, that will appeal to more users. It’s called Typora, and it offers that nice minimalist user interface and simple, rich text-like editor that I think most users will prefer. It’s also cross-platform, and it works on Windows, Mac, and Linux.

Best of all, Typora is free, at least for now. The app’s maker says that it is currently in beta, and it’s not yet clear what the price may be once this ends.

Typora doesn’t offer a side-by-side view—you can instead toggle between code and formatted text—so I don’t think I’ll ever want to use it myself. But I may have found a MarkdownPad 2 replacement, regardless. And once again I have Rafael to thank.

We were chatting the other day when he mentioned that he had moved to Visual Studio Code for writing, which he also does in Markdown. I’ve tried this several times in the past, but I had found the VS Code interface to be confusing and convoluted. And using it for writing would require the install of one or more extensions, adding to the complexity.

But spurred by his recommendation, I tried again. VS Code comes up in a too-dark (to me) color theme, but that can be changed. There are a number of superfluous user interface features, like its document mini-map and side-bar, that I have to manually hide. It doesn’t wrap text by default, since it is, after all, a developer editor. And you have to find and install a few extensions related to Markdown to get a more writing-like experience.

As confusing, Visual Studio Code doesn’t display Markdown files in a two-pane view by default; you have to enable this every time, and the keyboard shortcut reminds me of something out of Emacs: CTRL + K + /. Ah boy, at least there’s a toolbar button to toggle it.

And yet. I kind of like it. It works like MarkdownPad 2 mostly, and I can export to WordPress accurately. And it does a better job of syncing the two panes, visually, than does MarkdownPad 2. So I could see moving to this. Install, certainly, is quick, and I believe those configuration changes I mention above will normally take less time than the multi-stage MarkdownPad 2 install. And VS Code, unlike MarkdownPad 2, is actively supported and improving all the time.

Some may question the use of a developer tool for what I’ll call creative writing. But the reality here is that VS Code is designed to handle a diverse range of developer-oriented needs. And among them is documentation writing. What I’m doing with the product isn’t really all that unusual, or atypical for its purpose.

That said, I don’t recommend that casual users tackle Visual Studio Code. I recommend Typora instead. But at least there are options.

Anyway, that’s how I write, and what I’ve been researching for writing tools over the past year or so. I expect the options to keep expanding and improving, too. And maybe there will be even better choices to recommend in the future.