Markdown makes your life easier

From time to time it’s necessary to write down something directly in HTML. Usually it isn’t strictly code, it’s just some formatted text that you’ll paste into an HTML editor in WordPress or into a Raw HTML object or page in Sandvox or RapidWeaver. You may prefer to have it directly in HTML because there’s some other ready-made code you need to add somewhere, or because you just want to tweak it more than your favorite platform allows via its default visual editing tools.

HTML code is easy both to learn and to use, but if you’re writing a long text and want to focus just on the creative side for a while, writing and closing tags each time is a waste of keystrokes and concentration. Moreover, if you’re not an HTML expert you probably don’t feel safe in writing code by hand.

John Gruber, the author of Daring Fireball, created a simplified language to be used alongside HTML and called it Markdown. It has been very well received and now a bunch of text editors support it or are even specifically based on it.

Markdown’s syntax is defined just by few characters, in substitution for the most common HTML tags. For example, an h1 header in HTML is written this way:

<h1>This is my title</h1>

while in markdown you just need a hash:

# This is my title

One of the most boring things to write in HTML is a link (open an “a” tag, add url with quotes, then text, then close the tag…). In markdown you write your link enclosed in square brackets and then add the url inside a couple of parenthesis. Example, from this:

This is <a href="">My New Webite</a>!

to this

This is [My New Webite](!

Clearer to read and easier to write.

Instead of a couple of <blockquote> / </blockquote> you need only a “>” sign; “h2” is two hashes (##), “h3” three (###) and so on; italic and bold are enclosed inside one (*italic*) or two (**bold**) asterisks. Lists are automatically converted and nested. Whenerever you want, you can write regular HTML inside a markdown document, it will be correctly recognized as HTML.

Whenever you need to write a long text with links, blockquotes, lists, headings and some basic formatting, markdown is a good choice that becomes even better associated to a specific application. At this point there are two options:

  • If you want to focus on code, you’ll prefer an application with syntax highliting and a real time preview
  • If you want to focus on content, you might try an application whose interface is designed to remove any distraction

In the first group are Mou, currently in free beta, and MarkdownNote ($3.99 in the Mac App Store). This is a Mou’s screenshot:

You write your markdown inside the left window and the right window shows in real time how your text will look when converted in HTML.

The second group includes ByWord and iA Writer (both in the Mac App Store, $9,99). Here’s an example for the latter:

This second group’s goal is not exactly to help you code: instead, it’s to help you write, markdown is just a good tool to accomplish this result getting the rid of toolbars, buttons and other distractions, so you can format your text without moving your hands away from the keyboard.

Background and typography are designed to be relaxing and readable and you can use a full screen editor to hide everything you don’t need (menubar included).

There are many other apps, each one with its own implementation of markdown, so before you buy it check:

  • that it supports all the markdown syntax (or at least the part you’ll be using)
  • that it exports the markdown file to HTML (exporting to .rtf is a plus, because markdown is a good way to write long texts even if they’re not destined to HTML)
  • that you like its graphic interface…!

When you’re done, export your file to HTML, open it with any text editor, cut and paste just the code you need (usually a full HTML page is created and formatted with the application’s CSS: of course you can discard this code and use just what’s inside the body).


The full syntax is here, these are the most common commands (read your app documentation to see what/how is implemented, you may find less or more options):

#	h1
##	h2
###	h3
####	h4
#####	h5
######	h6


> blockquote

* unordered list
	* sub-element (1 tab)

1. ordered list
2. second element
	1. sub-element (1 tab)

this is some `inline code`

		this is a code block (2 tabs)

***	horizontal ruler

this is a [link](url).

this is a [link][a] with the url defined somewhere else.

You can use just the url embedding it in less-than and greater-than brackets:
Write am e-mail to <>.

this is an image: ![MyPic](path/to/image)