CloudBerry Explorer for Amazon S3

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.

Many Markdown Editors

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:

Screenshot from appstorm.com article 35+ Markdown Apps for the Mac

And this:

Screenshot from Mashable.com article 78 tools for writing and previewing Markdown

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.

If you want to host your own copy of StackEdit, the source is here.

StackEdit screenshot

Yes. I am sort of obsessed with Markdown


What is Markdown?

Markdown is a tool that converts text to HTML using a simple markup language. For example, this:

Formatted HTML

This sample text is bold. This sample text is italicized.

Here’s a list:

  1. List item 1.
  2. List item 2.
  3. List item 3.

Here’s a quote:

Everybody Has a Plan Until They Get Punched in the Face
– Mike Tyson

Here’s some code

if (true) {
   goto 10
}

Represented by this Markdown

**This sample text is bold.** *This sample text is italicized*.

Here's a list:

1. List item 1.
2. List item 2.
3. List item 3.

Here's a quote:
> Everybody Has a Plan Until They Get Punched in the Face

Here's some code

    if (true) {
       goto 10
    }

And this HTML

<p><strong>This sample text is bold.</strong> <em>This sample text is italicized</em>.</p>

<p>Here’s a list:</p>

<ol>
<li>List item 1.</li>
<li>List item 2.</li>
<li>List item 3.</li>
</ol>

<p>Here’s a quote:</p>

<blockquote>
  <p>Everybody Has a Plan Until They Get Punched in the Face</p>
</blockquote>

<p>Here’s some code</p>

<pre><code>if (true) {
   goto 10
}
</code></pre>

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:

Word doc download dialog

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.

DokuWiki diff

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:

Screenshot of a diff of a markdown file

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.