Month: December 2013

I’m learning WordPress, so this is my first attempt at a image gallery post. The gallery that comes with this theme isn’t quite as nice as I would like, but I’ll fiddle around with it later. For this learning experience, I simply picked an app I had used recently and took a bunch of screenshots.

So I was going to write a post listing a bunch of Markdown Editors for Windows, Mac, and the web… Really. But, then I started Googling, and I came across this:

And this:

You know what. That’s just piling on. 78 tools?!?

Anyway, it just so happens that I am composing this post in an editor not mentioned in one of those massive and not at all intimidating articles. It’s called stackedit.io.

StackEdit is a free, open-source Markdown editor based on PageDown, the Markdown library used by
Stack >Overflow and the other Stack Exchange sites.

By default, StackEdit stores documents in your browser’s local storage, but it can sync with Google Drive or Dropbox. It can also publish directly to several different places such as WordPress, Blogger, Tumblr, Github and others.

The Markdown looks like something you could paste into an email, and that’s the point. It’s human readable, but it can be converted into lovely, well-formed HTML.

Why I ♥ Markdown

Ask any one of my coworkers, and they’ll tell you that I take my documentation very seriously. One of my pet peeves is using Microsoft Word to maintain technical documentation. I think that Markdown has several advantages over Word docs:

Markdown is readable as plain text

I’m a Software Developer, and like most Software Developers, I have developed what is probably an unhealthy attachment to my text editor and to the command line. I like text documentation because it’s versatile. I can view Markdown text from the command line. I can view it in my text editor. I can view it just about anywhere.

I can view it in a web browser. No downloading necessary

We have all experienced this on the web before. You do your Google search. You see a link that looks promising and click it. Then you see this:

If you’re like me, you immediately close that dialog and move on to search results that don’t require any friggin’ double-clickin’.

I think that one of the reasons that Github is so popular is that you can create a lovely, formatted web page by creating a file with some Markdown in it. No muss, no fuss.

It’s text, so I can version it right along with my source code

This solves a lot of problems for us at work. We use a wiki called DokuWiki with a Markdown plugin that supports my favorite flavor of Markdown called Markdown Extra.

This is super useful because we can easily see what changed between versions, who changed it, and when.

It’s text, so I can diff it using my preferred diff tool

At work, we keep documentation on our web component in Word documents. These don’t change a lot, but when they do change, good luck figuring out exactly what has changed. If you’re lucky, the last person to edit the file turned change tracking on, but it’s nowhere near as simple as something like this:

Formatting options are limited so I don’t spend time puttering around with formatting

I think everyone has gone to battle with Microsoft Word over positioning a line break, or numbering a list, or indenting a block of text.

More Markdown for your editing pleasure

I will be posting links to a few Markdown tools and sites throughout the week. For now, here are some links to get you started.