Why I Use Markdown to Write for the Web

One of my favorite single-purpose apps – Brett Terpstra’s Marked – is on-sale through Christmas. Marked allows you to preview documents written in Markdown as you write them, so that you can see what they will look like online. Each time you save the document, Marked automatically updates the HTML preview. When I’m using a dual-monitor to write for the web, I have Marked open on the second monitor as I write on the first.

When I tweeted about the Marked sale, my friend Matt Stauffer made me laugh with his reply:

He then asked me to write about why Markdown is practical. Over the last 18 months or so, I’ve become a Markdown convert. Here’s why and how I use Markdown.

What Is Markdown?

First, a brief description of Markdown, from its creator John Gruber:

Markdown is a text-to-HTML conversion tool for web writers. 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).

If you, like me, were introduced to the Internet during the era of plain text emails and Usenet newsgroups, Markdown looks very, very similar to the rudimentary formatting used back then. Here are some simple examples. The following, written in Markdown:

##Heading  2
This text is **bold** and *italic*.  
I’m linking to [my website](http://www.mikehickerson.com). 
>; Ooh, a clever quote. 

becomes this when converted to HTML:

Heading 2

This text is bold and italic.

I’m linking to my website.


Ooh, a clever quote.

Here’s the full list of Markdown syntax. The variant of Markdown called MultiMarkdown allows you to do even more.

Why Do I Use Markdown?

Simplicity: Markdown uses plain text files, which means I can edit them using any app that writes and edits plain text. I’m not locked into a specific app, and I can be certain that my formatting will remain correct if I switch from one app to another. Further, because Markdown formatting is more compact and less intrusive than standard HTML, I can focus more easily on the text.

Ubiquity: Because these plain text files are small and simple, they can easily be synced across multiple devices using Dropbox. And, as I mentioned above, because Markdown formatting is built in to the text itself, it doesn’t matter which app I use. For example, I’m writing this sentence on my iPhone using Nebulous Notes while sitting in Dominos waiting for a pizza. I’m writing this sentence, however, on my MacBook using Byword.

Cleanliness: Clean HTML, that is. These days, I’m usually writing for later posting on WordPress, but I’ve also used Markdown for writing in Drupal, MailChimp, and several other CMSs. When I’m ready to publish, Markdown converts my text into clean, syntactically correct HTML.

Now, I know HTML, and if I wanted to, I could write the content in HTML. But when I’m writing, I want to focus on the writing, not on the coding. Later, when I’m coding, I want to focus on the “real” coding, not on cleaning up gobbledygook created by a word processing program. (I’m looking at you, Word! You too, Google Docs!) Markdown allows me to add proper HTML to my text, as I’m writing, without me shifting from writing-mode to coding-mode.

Further, if someone sends me a document that they want me to post online, I can convert it into plain text and recreate the formatting fairly quickly using Byword.

How to Use Markdown

To start using Markdown, all you need is:

  • A text editor
  • A way to convert Markdown to HTML

Any text editor will do. Both Mac and Windows ship with built-in text editors (TextPad and Notepad, respectively), and there are a plethora of text editors available for every OS you can imagine. Currently, my preferred text editors for writing (as opposed to coding) are Byword on OS X and Nebulous Notes on iOS. I also occasionally use nvALT. I keep in-progress documents in Dropbox, so they are available in whatever text editor I feel like using.

Note: Word processing progams, like Word or Pages, are not text editors. They add their own special formatting that you often cannot see. Word processing programs are great for writing for print or PDF, but terrible for writing for the web.

To convert Markdown to HTML, you can install Markdown on your site or system with the instructions at the bottom of this page, or use Dingus to convert the text for you. My preferred method, however, is to use an app like Byword or Marked. One of the nice features of Marked is that it keeps an HTML version of your Markdown document updated at all times, so you can simply copy the HTML whenever you’re ready to use it online. Marked also allows you to use your own stylesheet(s) in the preview if you like to see the document exactly as it will appear on your website.

My Markdown Workflow

Here’s how I use Markdown in combination with WordPress. This is my standard workflow both on this site and on the Emerging Scholars Blog.

  1. If I’m writing the post, I start it in either Nebulous Notes on my iPhone or Byword on my Macbook. I finish the text formatting in Byword, because I find the iPhone screen too small and the copy-paste method too clumsy for decent editing. If someone else has written the post, I copy the text into Byword and format it there.
  2. Using either Marked or Byword’s Preview Markdown feature, I copy the HTML and paste it into WordPress. (Be sure to paste it into the Text/HTML tab in the WordPress textbox.)
  3. I finish the post in WordPress by uploading any images, adding categories/tags, and taking care of any final formatting or editing.

Markdown can handle images just fine, but a text editor can’t upload images by itself. I also prefer to edit the captions and sizing in WordPress.

Do you have any questions about Markdown? Or your own suggestions for using it? Leave them in the comments.

1 thought on “Why I Use Markdown to Write for the Web

  1. Mike! You’ll be pleased to know that I found your post here through an organic Google search on ‘Byword Markdown WordPress workflow.’ and I’m pleased to say it provided just what I was looking for. First, I wanted to avoid installing one of the various WP Markdown plugins, so I can keep my WP installation as clean as possible. Second, it led me to the next logical step of just adding the Publish feature that’s been added to Byword since you wrote this post.


    I swear I’ll get over to London to see you guys in 2014. I miss you, and this lack of travel is getting just a little boring. 😉

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s