Tag: markdown

Lately, I’ve had (or created) several opportunities to talk about using plain text file (and markdown syntax) – how great I think it is for writing and (more importantly, really) how perfect it is for making sure your stuff remains ubiquitously compatible and futureproof.

Now, simply saying these things isn’t enough to make everyone (or anyone) suddenly slap their forehead and switch to plain .txt files; to be honest, my conversion wasn’t an overnight thing – yes, I can find plain text back as far as I have files, and even .md (markdown) files from two or three years ago, but in most cases the pattern until recently has been pretty clear: use those ‘primitive’ formats to do some initial work and note-jotting but, once the serious work begins, copy the whole thing into something like Word.¹

I’ve changed my methods, though; my outlook has shifted. I’ve started to see more benefits from working in plain text, all the time. Here are the big wins for me:

Universal Availability

I can edit chapters on my phone while I’m at Grease Monkey, poke at them on my tablet while the kids watch Super Why, open them in a half dozen apps on my mac, windows, or linux machines, and (and this is really important) I don’t lose any fidelity or formatting because I opened them in different programs on different platforms.

Imagine what your word document would look like after a few days of bouncing it between “word-compatible” programs on your PC, Mac, Linux box, iPad, iPhone, Chromebook, and Android tablet. Even RTF, which is supposed to be multi-platform, would suffer grave deformations over time, given this kind of abuse.

Because that’s what this sort of situation is for those kinds of files – bouncing them around to different systems and opening in different programs is abuse. (And heaven help you if you want to go multi-platform with cloud sharing on something like Scrivener.)

Text files? Text files don’t care.

Universal Transferral

Eventually, you need to ship, and you probably need to ship in something other than plain text.² When I need stuff to go out, I can take my lovely markdown-enhanced text and put it out into the world in whatever format is needed.

As an example, I finished an academic paper last week with a couple dozen footnotes and within about four minutes I’d published it with full, pretty formatting to a Word doc, PDF, a forum post, and my blog, again without losing any fidelity in the formatting, without needing to do any additional formatting, and without changing the core document (a .txt file) in any way.

Also last week, I sent my work in progress (which comes in at somewhere north of seven hundred pages) off to a couple folks. One of them got it as a word .doc, one of them got it as an .epub (took me about a minute, total, to create), and when I get their feedback, I’ll be right back to working on the text files. Those other files are just outputs to me – something I create, but don’t work in; like exporting to PDF.

That said, the fact that I can export to Word, or epub, or html, or pdf, or rtf, or odt or… well, whatever… means that the work gets out in the best way possible, right away.

The Challenge

I said something similar to those two points a couple weeks ago on Google+ and Ryan Danks (who’s been struggling with plain text and markdown) said:

Could you maybe do a blog post on your workflow? I think this might help out a lot of people I know who are still trying to find their groove.

The answer, of course, is yes. Sorry it took so long.

1. Dropbox is my Co-pilot

I honestly don’t know what my working/writing environment would be like without Dropbox. It seems like hyperbole to say ”My life would be completely different without Dropbox.” and it is, sort of.

Except that, at the micro-level, Dropbox touches so many of the individual elements that make up my day that I can’t see how, at a macro-level, it isn’t true: a big, big chunk of the stuff that makes of my life would be fundamentally different without Dropbox.

Now, these days, there are other options that give you similar functionality – I could probably manage the same basic workflow in OneDrive or Google Drive or SpiderOak (not iCloud, since I’m using a lot of non-Apple stuff, but lots of other people could) – and that’s great, but since I’m talking about my real workflow, I’ll be talking about Dropbox, and simply trying to point out when and where other options are also available.

My Dropbox

Here’s where I do pretty much all my work.

I want to make this clear: I work inside my Dropbox folder and, while I certainly appreciate that it both backs up and provides versioning of all the files therein, the critical thing for our purposes is this: Dropbox makes sure that everything stays up to date on all my devices.

That’s critical; I need all my stuff to be ready-for-work, regardless of whatever thing I pick up to work on.

2. (Almost) All the Tools, All the Time

Once I’ve got to the point where everything is at least theoretically available on all my devices, step two is giving myself basically the same tools and options.

This is really where the choice to work in plain text pays off, because since I’m working without the requirements and limitations and… fragility of file formats like .doc or .rtf, when it comes to writing and editing, I get full functionality no matter where I am.

I do have to sacrifice a bit in terms of shipping when it comes to different platforms: it’s simply not as easy to export from markdown/plaintext to some other file format if I’m on my phone, for example. I’m sure in three years, it’ll be a piece of cake to export right from markdown to .epub while I’m sitting in the doctor’s office, but at the moment, that’s what I give up, and I’m fine with that; I don’t need to be able to ship every minute of the day.

Come to that, there are tools I like better for different kinds of exporting. Pretty much any markdown editor outputs to html just fine, but rtf and pdf is a little bigger deal, word docx export gets a little more rare, and there’s really only one program I have that’ll go right to epub, no waiting.

Again, I’m fine with that. I’ve looked at the options that were available even three years ago, and I think it’s clear this is an evolving and constantly maturing environment: I expect my options in the future will always be better than they are at this moment, and I’m pretty happy with them now, so I’m very comfortable hitching my wagon to the markdown star.

Anyway: enough talking. Here are some examples of the options I’m talking about.

3. Tools

Mac

I’m starting with Macs because (for some historical reasons I’m not particularly interested in) Markdown was taken up by the Mac community sooner than elsewhere. It’s making huge inroads elsewhere, with surprising speed, but Mac and iOS still have some of the best Markdown tools.

My tools:

I’m going to break these down in Right to Left order: nvALT, iA Writer, MacDown, and Ulysses III.

nvALT

nvAlt is my “Note taking” tool. It opens with a keystroke, and all I have to do to create a new file is start typing: it names the new file the same as whatever I type into the first line, and lets me view both the current file and everything else in the working directory³, right from the main window, like so:

The program is compatible with Markdown, and provides a nice preview window that will show you what your text will look like when you export it somewhere…

As an added bonus, if you’re working in this screen and decide you need something more robust, there’s a simple keystroke option that automatically opens whatever file you’re working on inside whatever “bigger” editor you set up as the default, which brings me to…

iA Writer

Probably the easiest way to explain iA Writer is “Writemonkey for Mac, but different.”

It’s set up to be a ‘distraction free writing environment,’ but what it really is is friction free – you just open something and get to work. What it lacks in Writemonkey’s “kick you in the ass to get you writing” features, it more than makes up for with great workflow tools and incredibly robust support for markdown, multi-markdown (footnotes, bibliographies, tables), and both the importing and exporting of files — I’ve been going through some of my old stuff and transferring it from (for example) .docx files to plaintext, and iA Writer has been invaluable for this process: literally all I have to do is drag a Word file onto the iA Writer icon, and I suddenly have a nice, clean text file with all the formatting syntax preserved.

It is, if you’ll pardon me, fucking magic.

(Editing to add: While adding web links through this document, iA Writer gave me yet another reason to love it – it vastly simplifies the process of adding links to a document, and makes writing posts like this one much easier. So much love.)

MacDown/Byword

iA Writer has a very nice preview window, but sometimes I like to work with the preview open all the time in a side-by-side arrangement, and for that I use MacDown.

Also, and this isn’t nothing, I really do like the fact MacDown “color codes” my text while I’m working on it. Ulysses III does this as well, and it’s pretty great for those times when you want to make sure your italics are right where you meant them to be. I imagine this is a slightly bigger deal for developers than writers, but the fact is I sometimes go to MacDown over iA Writer simply because the MacDown screen is more interesting to look at.

For those of you who use Byword and can’t believe I don’t list that in here somewhere, just pretend this entry is for ByWord – the two programs have similar inspirations and ancestors, and feel pretty much identical to me. I just use MacDown because it’s free, and I spent all my App-allowance on…

Ulysses III

How should I explain Ulysses?

Let’s go with “Scrivener, for plain text.”

Basically, Ulysses is a very good Markdown and Multi-markdown editor that is also very good at managing big writing projects. I will provide an example.

When I finished up the first draft of current work in progress, I had a single text file that was thirty-one chapters and about 700+ pages long. There’s nothing wrong with that, but it’s a bit of a pain in the ass to open the thing up on your phone and scroll down to chapter twenty-three, you know?

What I did once I had Ulysses was take the original file, open it up, then jump to each chapter heading and say “Split the file here.” In the three-panel view in Ulysses, that gave me something that looked like this (click to embiggen):

And in finder/explorer, looked like this:

Basically, Ulysses chopped the big file up into a bunch of little files that are much more manageable in other programs, while still being treated by Ulysses as one complete meta-entity.

(Those last two files are docx outputs I created for workshop feedback by selecting specific chapters and telling Ulysses to export them to Word.)

The cool thing is the program also lets you fiddle with the structure of the meta-document and then stitch things back together in whatever order you like. Here’s a shot of me rearranging some chapters into a different order, simply by dragging things around in the preview window.

It has no effect on the files themselves, except in Ulysses, until I recombine all the files, or export stuff.

And it’s worth noting Ulysses exports are really quite pretty. Here’s the epub version of the work in progress.

Now, Ulysses’ ability to chop up a big project into smaller bits is great – very useful for me, right now – but with a little forethought early-on (or a LOT of cutting and pasting, today), I could have accomplished the same thing with notepad. I’m glad I didn’t have to, but I could have.

The main value of working on things in smaller pieces is more easily navigable files, which are much easier to work on when I’m using my phone or tablet.

So let’s talk about working on a phone or tablet.

Phone or Tablet

Before I get into specific tools, I want to talk philosophy of use.

Here’s the main thing you need to keep in mind when you’re looking at tools to use on a handheld device:

It isn’t about whether the App can open a file of the right type, it’s about whether it can work right inside Dropbox, without downloading files.

Dropbox, as you probably know, doesn’t download EVERYTHING to your mobile devices, the way it does on your laptops or desktops. Instead, it mirrors the directory, shows you what’s there, and only downloads something if you really, really want it.

That’s kind of useless for what we’re doing. I do not want to download a file, fiddle with it, save it, then reupload/overwrite/update the Dropbox version, when I’m working on my phone. I want fast, reliable, and as frictionless as possible; I want Dropbox to be Dropbox.

In other words, I need a program that works right inside my online Dropbox folder, effectively making Dropbox as useful as Google Drive with it’s built-in editor. (And, once again, that’s a lot easier when I’m using plaintext files, and a lot HARDER when I’m using .docx or whatever.)

Android

For Android devices, I use Jotterpad, which pretty much hits every target I place for mobile writing: reliable, edits directly in Dropbox, and understands markdown (all the little formatting buttons it provides format things using markdown syntax).

Here’s Jotter looking at my Writing folder inside Dropbox:

Here’s the view of the nvALT directory…

And this is working on edits, in portrait.

iOS

I don’t work on any iOS devices at this time, but I know iA Writer has an iOS version (my daughter has it on her iPad) and I’ve heard very good things about Drafts – just make sure it works inside the online version of your cloud service (iCloud or Dropbox or whatever – Drafts does), or (at worst) actually downloads full versions of the drive down to the device, and you’re good.

Online Tools

There are a number of online Markdown editors, especially awesome when you’re working on a Chromebook (because Google Docs get a disappointing ZERO on markdown support), and for those I use the same criteria as the mobile devices: I only use something that syncs with and effectively works entirely inside my online Dropbox drive.

My current favorite is Dillinger, which syncs with Dropbox, Google Drive, Microsoft’s OneDrive, and GitHub, pretty much giving you full markdown writing functionality wherever you’ve got web access. Here’s Dillinger asking which file to open in Dropbox:

Plus, if you don’t have another option, it provides a pretty good list of export options, if you can’t ship any other way.

The writing interface with Dillinger is also good, with a solid preview window that’s pretty much just like any other markdown editor app on a desktop.

Windows/Linux

Speaking of desktops, here’s what I use on my Windows and linux machines.

First, MdCharm, which was originally built for Linux and ported to Windows. I like it because I can use it on multiple platforms, the “project” window that lets me use multiple directories and my working space (it makes it quite compatible with the stuff created by Ulysses), and it has good options for importing and exporting.

One of the other things I like about MdCharm is its longevity – it’s been around long enough to still describe itself as a “wiki editor” that “now supports Markdown” — that’s a program that’s been around the block a few times, and it still actively supported. Good stuff.

Finally, there’s Writemonkey, which I put to use when I’m doing first drafts. It’s a great program that is absolutely one of the best for getting me to sit my ass down and WRITE, but the problem is I do a huge amount of my first draft writing on my macbook air now, so this program doesn’t see as much use has it has in the past (my current WIP was pretty much all written in Writemonkey, but it may be the last big story that is, unless the developer creates a Mac version, or someone else makes something very much like it).

Conclusion

So that’s my workflow. Rather than try to sum it up, I’m going to leave this as is and put it up where people can ask questions and get clarification.

Hope this helps.

Edit to add:

Here’s a quick video tutorial to illustrate some of the things I mentioned above.

I’ve been using plain text for writing for a long while now, especially when writing for the web. It started with my extensive use of wikis for several geeky side projects.

I loved (and still love) wikis; initially for their ability to allow multiple authors to collaborate on a project, but then (and eventually even moreso) because the wiki platform’s simple syntax allowed a user (any user) to build web pages by using relatively simple rules and no html coding. Those rules were great… the only problem was, I couldn’t use them everywhere, for all my projects, because only wikis really used them.

I tried, though. Boy did I try. Digging through my archives, you can find plaintext files from well over a decade ago, in which I’d made use of wiki-style syntax to mark up the basic text.

Ultimately, you see, I wanted to get everything I wrote into plain text files, by default.

What’s the big deal with plain text?

Plain text files – as you can probably deduce – are files that include only your text, with no additional formatting. That means you can open them in pretty much any text editor or word processor, on pretty much any digital device (PC, Android, iPhone, iPad, Mac, Linux… your wifi-connected television), and they will look exactly the same.

Always.

In terms of files meant to convey the written word, there is virtually no other editable file format for which this is true; as soon as you start talking about even basic, rich-text formatting (like bold and italics), you’re also talking about proprietary files like .doc, .docx, .rtf, or something similar. Even html, as basic as it can be, is in no way reader-friendly in its raw, unprocessed state. To paraphrase Michael Schechter:

• Plain Text is Portable – The files are smaller allowing for large libraries of text files to move quickly from a folder in the cloud to your device of choice, and take up less space.
• Plain Text is Flexible – It doesn’t matter what type of machine you’re using or what writing program. There is no file incompatibility; no broken formatting or files that cannot be opened.
• Result: Plain Text is Ubiquitous

Don’t get me wrong: word processing programs provide some really cool and (sometimes) even useful tools, but one thing they cannot do is guarantee what I write today will be readable ten years from now. On the other hand, if I’m using plain text, and computers still exist, I’m good. If I have to turn everything into hard copy and flee to my apocalypse bunker, I’m still good; plaintext guarantees that even the most crude PC-to-printer file dump will output exactly what I typed.

Put another way, every story I have saved with a .doc extension is a file I worry I’m going to have trouble opening in the future – either opening at all, or opening in a way that loses some of the fidelity.

And let’s be honest: from a workflow point of view, no one needs the gizmos and gadgets in word processors like Word or Pages to get writing done; usually all that shit just gets in the way. I mean, it’s right there on the tin: word processor – that’s a tool capable of being used for writing, but optimized for formatting text for printing – from my point of view, it’s like opening InDesign to write a first draft.

Most of us opening Word for writing are just using a default document template anyway – in other words, we aren’t using all or even most of the tools provided by the program. Opening a word processor for drafting, writing, and editing is like going out to the garage, starting your car, and leaving it running for an hour so you can charge your cellphone.

Word processors can be useful when you’re at the point where you want to creating fancy formatted documents, but for everyday use, they’re a bad habit, not good practice, and one I try to get away from.

But… formatting?

“Doyce,” you say, “this is all nice, but we still need to be able to bold and italicize text. We need to be able to create headers, block quotes, lists. And we need to do so in a way that our boss, co-workers and friends can read. We need to create links and we need to get it all in a format that works on any website.”

That’s where Markdown comes in.

Markdown

Markdown, and the many different editors that now use it, was the answer I needed: plain text, but using various characters to define (not format) the text.

Quoting John Gruber, Markdown’s creator:

Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

In simple terms, it allows you to write entirely in plain text in a way that can easily be exported into something formatted. Markdown syntax (it’s not a ‘language’) is easy to learn and, today, can be used to create more than just HTML/XHTML – I can export my markdown formatted plain text files to word, pdf, web pages, open office, and damn near anything else I need, in seconds.

From headlines to lists, to images, to links, to footnotes, I simply assign meaning to text passages by entering some easy to remember characters. No need to reach for a mouse or click on a drop down menu; I just type.

Just. Type.

The beauty of this should be obvious. Instead of worrying about how your output looks, you can concentrate on what your words are saying.

The Tools I Use

Because I want to get it down somewhere and, maybe, help someone else get started using Markdown and plain text files, here is the list of every tool I use for Markdown.

Best of all, most are free.

PC

• WriteMonkey was the first more-than-notepad plain text editor I made serious use of – a markdown editor years before I’d even heard of markdown, or before it called itself that. Donationware that got to where it is by focusing on distraction-free writing, WriteMonkey is my favorite tool for writing longer stuff, and is particularly awesome because it provides out-of-the-box exports directly to .doc format, which is great for the point in a writing project when I need to move from editing drafts to sending to a workshop, editor, or agent. I’ve written the last 300 thousand words worth of stories in WriteMonkey, saving to plain .txt format, and I don’t regret it for a second.
• MarkdownPad 2, which focuses more on being a markdown editor than being a pure writing tool, but which is still a very nice, easy to read interface. There’s both a free and pro version.
• MdCharm isn’t quite as glossy as Markdownpad, but makes up for that by being multiplatform: I use it in both Windows and Linux distros, and because of that, the fact that the free version supports export to PDF, HTML, and ODT, and its support of multi-file projects, it’s seeing more use right now than either of the other two I’ve listed.

Mac (and iOS, sometimes)
I’ve done a lot of experimenting with different markdown tools on my mac, and taken long hard looks at pricier options like ByWord (which, at ten bucks, is the go-to option for many Mac and iOS users) as well as Ulysses III (the $45 Rolls Royce of editors that provides Scrivener-style “sheet” organization and out-of-the-box export to ebook formats, which is really useful to me), but I can happily recommend cheaper options.

• MacDown – As far as I’m concerned, this is basically the same feature set as ByWord, but free, and I love the interface. That said, ByWord has an iOS version, and MacDown doesn’t.
• Ulysses III – I’ve been using this for revisions and editing, because it lets me pull everything in a directory into a single organized view – this lets me leave each chapter of a story in its own tiny text file, but work with them as a unified whole. It’s sort of like Scrivener, if Scrivener worked with plaintext files that will remain universally compatible, rather than proprietary files of its own that… won’t.
• iA Writer – this one costs five bucks, but it has a couple great things to recommend it:
  • It can important .docx files and convert them to markdown simply by dragging the .docx file to the iA Writer icon and dropping it. This is incredibly useful to me right now, as I’m going through all my old writing and gaming stuff and converting it to plaintext.
  • There are versions for the iPad/iPhone as well (Kaylee has it on her tablet), and I’ll pay five bucks for an excellent editor that works on my mobile devices, which brings me to…

Android
The bad news: there aren’t many reliable Android-platform markdown apps. The good news: there is one, and it’s really, really good.

• Jotterpad – which syncs beautifully with Dropbox and does everything I could hope for from a mobile device editing tool, and a damn sight more.

Finally…

WordPress

No, I don’t even write my blog posts in HTML anymore: all my WordPress installs have the Jetpack Markdown plugin, which lets me draft everything using Markdown syntax, drop it into a new post, and watch it all go up without a hitch.

I’m also thinking about whether or not there’s anything cool I could do with a markdown editor, Dropbox, and DropPages, and maybe there isn’t for me, but there might be for someone else, so I’ll mention it.

Forums

I also administer a couple of forums, and I’ve dropped the WYSIWYG editor (that broke whenever you pasted in stuff from Word) for integrated Markdown (which doesn’t) and have slowly, sneakily been teaching everyone on those sites how to format their post and (completely by accident, don’t know how that happened), how to use Markdown.

When All I Have is a Browser

Maybe I’m on a chromebook. Maybe I’m on a public machine, or someone else’s. That’s when I head over to Markable, Dillinger, or Writebox (which has Chrome and mobile app versions as well).

What’s Left?

• Email. I want markdown support in Gmail. Ditto Google+ (though it already kind of does Bold and Italics in a half-assed way).
• Google docs – I’ve been using this script to convert old google docs to markdown, but… yeah. I’d love if I didn’t have to.

The End

This is mostly for me, to be honest: I just wanted to get everything down somewhere, so I could document where I am right now with my network of Markdown-using tools.

But maybe it can be for you – maybe this will help someone future-proof their work, and if so, awesome.

Questions? Ask!