A Markdown Primer
Given the importance we attach to the creation of well-structured, semantic markup you might wonder why we’d advocate the use of Markdown as a means of generating clean and well-formatted markup. (Markdown, for creating markup? A contradiction, surely?)
The reason is that we use it day in, day out to make the process of content creation and writing markup easier. Once you have an understanding of how markup works, you’ll love Markdown’s simplicity; it makes the writing in writing markup a breeze.
To quote Mr Gruber, Markdown’s creator:
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).”
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
Put simply, Markdown enables you to focus on creating well-crafted content in your plain text editor before converting it into valid markup. Sounds perfect. So, how does it work?
Show and Tell
The easiest way to introduce the principles of Markdown are to run through some examples.
If you’re not familiar with Markdown’s syntax you might be forgiven for thinking that the examples below look just like plain text. That’s because they are. To explain the foundation of this emphasis on simple, clear text-like formatting Gruber states:
While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
So, let’s jump straight in and get started by looking at some examples.
Writing a paragraph is as simple as writing a paragraph:
This is a paragraph. Admittedly a very short paragraph that comprises nothing more than two sentences.
Parsing this results in the following:
<p>This is a paragraph. Admittedly a very short paragraph that comprises nothing more than two sentences.</p>
Typing the following will give you an
<h1> followed by an
An H1 Heading ============= This is an H2 -------------
Running it through the Markdown parser transforms the above, easy to read plain text, into perfectly valid markup as follows:
<h1>An H1 Heading</h1> <h2>This is an H2</h2>
Headings can also be designated with a
# (hash) marker, where the number of hashes indicates the corresponding level of heading, as follows:
#H1 Heading ######H6 Heading
Phrase emphasis is simple, by wrapping content in either asterisks or underscores to indicate spans of emphasis, adding
__strong emphasis__ (asterisks -
**strong emphasis** - are functionally equivalent).
Lists are equally simple. Unordered lists employ asterisks, pluses, and hyphens (*, +, and -) as list markers (as with phrase emphasis, you’re free to choose your preferred list marker). The following is an unordered list:
+ Bedtime for Bonzo + King Kong + Every Which Way But Loose
Changing this list to an ordered list is as simple as changing the list markers to numbers followed by a period, as follows:
1. Bedtime for Bonzo 2. King Kong 3. Every Which Way But Loose
As the preceding examples suggest, the beauty of Markdown is the ease with which it makes the creation of readable and editable content. Back to Mr. Gruber:
Markdown is not a replacement for HTML … The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format.
This emphasis on ease-of-writing is one reason why Markdown has been embraced as a lightweight markup language for several content-management and blogging systems, including WordPress, Movable Type, Drupal, Expression Engine and many more.
Embracing a Content Out Approach
In Transcending CSS: The Fine Art of Web Design, Andy Clarke introduces the idea of a content out approach as follows:
You should always start writing a document by first using only structural elements such as headers, paragraphs, lists and quotations.
With its plain-text-like syntax, Markdown is a perfect medium for adopting a content out approach. What makes it so appealing is the way in which it makes writing well-formed, structured markup so easy.
By default it produces lean, structured and well-formed (X)HTML, ready to be expanded into a clean and efficient web page or added to an existing one. This approach results in nothing but structured markup, ready to receive some CSS goodness, not a needless div or span in sight.
By enabling you to write easy to read content that can be converted quickly and painlessly into valid (X)HTML, Markdown allows you to generate well-formed content with the minimum of fuss. The easiest way to get a feel for it is to try out the Dingus at the Markdown site.
Getting Jiggy With It
Although HTML is relatively easy to craft by hand, Markdown is often easier and faster to write. Also, just as important, it’s easier to read. Mr Gruber outlines the philosophy behind Markdown as follows:
Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Readability, however, is emphasized above all else.
Let’s look at a quick comparison, here’s a block of markup, in Markdown:
Markdown ======== Markdown is a lightweight markup language designed to ensure maximum readability of both its input and output forms. John Gruber, Markdown's creator, states: > 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). Originally implemented in Perl, Markdown is now included with, or available as a plugin for, several content-management systems. Basics ------ Getting started with [Markdown] is easy. The language takes many cues from existing conventions for marking up plain text in email. ###Further Reading 1. [Markdown Syntax] 2. [The Markdown Dingus] 3. [Wikipedia] : http://daringfireball.net/projects/markdown/ "Markdown Overview" : http://daringfireball.net/projects/markdown/syntax "Markdown Syntax Documentation" : http://daringfireball.net/projects/markdown/dingus "Something whose name is either unknown or forgotten." : http://en.wikipedia.org/wiki/markdown "Wikipedia"
And the same, this time in HTML:
<h1>Markdown</h1> <p>Markdown is a lightweight markup language designed to ensure maximum readability of both its input and output forms. John Gruber, Markdown's creator, states:</p> <blockquote> <p>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).</p> </blockquote> <p>Originally implemented in Perl, Markdown is now included with, or a vailable as a plugin for, several content-management systems.</p> <h2>Basics</h2> <p>Getting started with <a h ref="http://daringfireball.net/projects/markdown/" title="Markdown O verview">Markdown</a> is easy. The language takes many cues from existing conventions for marking up plain text in email.</p> <h3>Further Reading</h3> <ol> <li><a href="http://daringfireball.net/projects/markdown/syntax" title="Markdown Syntax Documentation">Markdown Syntax</a></li> <li><a href="http://daringfireball.net/projects/markdown/dingus" title="Something whose name is either unknown or forgotten.">The Markdown Dingus</a></li> <li><a href="http://en.wikipedia.org/wiki/markdown" title="Wikipedia">Wikipedia</a></li> </ol>
Looking at the two examples above, the former is clearly cleaner and easier to read, yet both achieve the same end result. Therein lies Markdown’s beauty.
Getting Started Is Easy
Markdown is easy to configure and is supported by a number of popular writing platforms including, Movable Type and Wordpress. Should you be writing your well-formatted markup on a Macintosh, it’s also possible to integrate Markdown with our personal plain text editor of choice BBEdit.
TextMate has built in support, and there are plugins for many other editors including Coda and Vim. Ever helpful, Mr Gruber provides full instructions which will get you up and running in next to no time.
If you ever plan on doing any writing for the web - and if you’re reading this you probably are - Markdown is an indispensable tool to add to your toolkit.