Introducing Markdown on OS X

Screencast

Markdown is a formatting syntax that lets you write plain text that can be converted to HTML, without the need to write millions of angle brackets. Markdown uses symbols to indicate common HTML tags such as headers, emphasis and links. It has also been expanded on with efforts such as MultiMarkdown which offer support for more formatting options like rich text format (RTF).

In this tutorial, I'll introduce you to Markdown, explain why it’s awesome and how to start using it on OS X.

Introducing Markdown

Markdown was created by Daring Fireball’s John Gruber. It was designed to an easy-to-read, easy-to-write plain text format that could be converted into structurally valid HTML. The biggest feature of Markdown is that a document written in the syntax is readable as is; you don’t even need to understand Markdown, the tags just make sense.

Markdown has been expanded upon by different people to add features that the original version did not support. One of the most commonly used extensions is Fletcher T. Penney’s MultiMarkdown which focussed on extending Markdown so it could be used to write offline documents instead of just HTML. When an app claims to support Markdown, it is often the MultiMarkdown extension that it supports.

Originally there were two parts to Markdown: the syntax and the conversion tool. Support for Markdown, however, has meant that there is no need to use a command line to convert documents to HTML. Instead Markdown is supported in a wide variety of apps and web services.

Reasons to Use Markdown

The best thing about Markdown is that it makes writing formatted text extremely easy. If you’ve read any of my previous tutorials you may have realised I like to do things efficiently. Choosing a font size and style from a dropdown menu every time you want to create a heading, and then changing things back for the body text, is not efficient. Markdown lets you format your text with simple characters.

Markdown lets you write what you want in easy to read plain text that can be converted for whatever purpose you want. I can write an email response in Markdown and convert it to RTF. If I think my email response might be worthy of turning into a blog post, I can convert the same Markdown into HTML. This flexibility is one of the things that wins Markdown so many fans.

Markdown is just plain text. You can open, and read, Markdown documents on any computer. It doesn’t use a proprietary file format like Microsoft Word does so you don’t need to worry if a friend’s computer has the latest version of Office installed just to access something you’ve written.

There are many other reasons to use Markdown. These are just a few of the reasons I use it. If you start to use Markdown, you’ll quickly develop your own list!

The Markdown Syntax

Most HTML documents are relatively simple composed. The main formatting options used are:

Tip: In Markdown lines and spaces have meaning. For example, a header must be on a new line and to separate paragraphs, one or more blank lines are used.

Headers

Header tags, <h1>, <h2>, etc. are mainly written in Markdown using the # symbol. To write a header, start a new line with one or or more #s followed by the header text. The number of #s you use determines the level of header. # results in a <h1> tag while ### results in a <h3> tag.

Paragraphs

Paragraph tags <p> are added to any blocks of text that do not have an otherwise assigned tag. To split a document into multiple paragraphs you need to leave a blank line between each paragraph of text.

Links

In Markdown there are two ways to write links: inline and reference. I prefer to use the inline method, I feel it’s cleaner and easier to use so I’m going to focus on it. If you’re interested in reference links have a look at the Markdown specs. To write a link, surround the text you want to be the link text in square brackets. Immediately after the closing square bracket add the url for the link in regular brackets.

Bulleted Lists

To write a bulleted list in Markdown you can use either an asterisks, a plus symbol or a hyphen. Put each list item on a new line and start it with your choice of symbol followed by a space and then the item you are listing.

Emphasised and Strong Text

Markdown supports both emphasis tags <em> and strong tags <strong>. To write emphasis tags, put a single asterisk or underscore either side of the emphasised text. To write strong tags, instead use double asterisks or underscores.

This is *emphasised* and this is **strong**
becomes...
This is <em>emphasised</em> and this is <strong>strong</strong>

Writing and Exporting Markdown With Byword

I am writing this tutorial in Byword. I know for a fact that Computer Tuts+ editor Johnny Winter writes all of his in it too. Byword bills itself as Simple and efficient text editing for Mac, iPhone and iPad and lives up to that promise.

Byword provides you with a complete Markdown workflow. You use Byword like any other text editor, however, when you type characters that symbolise something in Markdown, Byword provides a live preview: headers become bold, link URLs are a lighter grey so that they do not interfere with reading the text, emphasised text becomes italicised.

Byword’s available on both OS X and iOS so you can get a consistent experience across your devices. Available from the Mac App Store.

Byword’s main competitor is iA Writer which also offers a complete workflow, very similar features and both Mac and iOS apps. It’s also available from the Mac App Store.

Other Markdown Apps

If you need more powerful export options than Byword offers, Marked 2 is often seen as the gold standard. You can’t write directly into Marked 2, it is just a previewer and exporter. To work with Marked 2, open the same file in your text editor of choice and Marked 2. As you enter text into your text editor, or move around the document, Marked 2 will detect this and update the live preview.

Marked 2 lets you export your Markdown files to HTML, Word files and PDF files. You can also set up the previewer so that it mirrors the CSS of your website so you can get a live preview of how your blog posts will look when you post them online.

If you like to keep a diary, the popular journalling app Day One supports Markdown. Rather than have to deal with exporting, Day One automatically displays Markdown as rich text when you are not writing or editing an entry.

Editing a Day One entry in Markdown followed by Day One's display of the result.

nvALT 2 is a note taking app that supports Markdown. It is a fork of Notational Velocity which Jonathon showed you how to use in a Text-Based Notes System. While Notational Velocity doesn’t support Markdown by default, the nvALT 2 fork does.

Web Services

As Markdown was originally designed for web writing, some major content management systems, or CMS, support it out of the box or with a plugin.

Wordpress doesn’t support Markdown by default but there are loads of plugins that let you add it. I use Jetpack Markdown for my own Wordpress site.

Finally, John Gruber’s original Markdown Dingus is a web service that lets you easily convert Markdown text to HTML. To use it, either copy or type Markdown text into the editor and click Convert. You can then copy and paste the HTML export to wherever you need it.

Conclusion

In this tutorial I’ve shown you how to write with the Markdown syntax and explained why Markdown is awesome. I’ve also shown you how to write and edit Markdown in Byword and looked at a few of the many apps and web sites that support Markdown.

If you’ve a favourite Markdown editor or workflow please let me know in the comments.