Them's Good Broth! | In Praise of Markdown

12 May 2012

In Praise of Markdown

“A Quick Intro to Using Markdown”

I hate word-processors. They are the spawn of the devil, for anyone of an artistic temperament. Ugly, bloated and stinking of corporate dullness, they sit there, sucking the very creativity out of you. Every time someone sends me a Word document, a bit more of my soul withers and dies. And it’s just as bad when I have to write up some kind of formal document myself. Even though I’ve eschewed Microsoft and its evil bug-ridden virus-infested software for years, I still feel the bile rise in my throat when I fire up the equally ugly-stick-beaten freebie alternative, NeoOffice, on my mac.

Quite apart from the fugliness, the launch times measured in ice-ages and the general stinkiness of word-processors, I hate using the damned things. I hate their stupid impenetrable style menus. I hate the way they seem to switch fonts willy-nilly. I hate the way pasted in text never formats up the same as existing text. I hate their stupid use of fucking tables. I hate the way they make the lovely practice of crafting words and sentences feel like having your teeth extracted, without anaesthetic. In short, I hate them.

If any of the above rings a bell with you, then meet Markdown.

Markdown [created by Apple pundit John Gruber] is a really easy to learn syntax for formatting [or ‘marking up’. Do you see what he did there?] text, which can then be converted into PDFs, HTML etc. You can write Markdown in any text editor, so no need to fire up some huge bloated word-processor, and there are also some nice looking dedicated Markdown editors, which make writing a pleasure again.

More on that later, but first let’s take a look at this Markdown syntax itself. I said it was easy to learn and, if you’ve been frequenting internet forums and the like for any length of time, you probably already know some markdown --although you might not know that you know it!

Ever seen anyone on a forum use asterisks to emphasise some text? Well, that’s Markdown. Most forum software doesn’t understand Markdown, so just shows those asterisks as asterisks but, with forum software that did understand Markdown, or working in a text editor that understands markdown; instead of those asterisks, you’d see italic text. It’s really that simple. with Markdown, instead of having to pick through stupid style menus, or highlight text and apply formatting, you just stick the appropriate punctuation at the beginning and end of the word, line of text or paragraph and, when you export to PDF, or HTML, or whatever, Markdown automatically converts that to nicely formatted text.

Some simple examples: showing the syntax and what it does:

One asterisk gives you *italic text* – One asterisk gives you italic text

One underscore gives you _italic text_ too – One underscore gives you italic text too

Two asterisks give you **bold text** – Two asterisks give you bold text

Two undersores give you __bold text__ too – Two underscores give you bold text too

Hash symbols give you headings in various sizes. Markdown follows the HTML convention that size 1 is the biggest and size 6 the smallest:

#A Size One Header#

<h1>A Size One Header</h1>

##A Size Two Header##

<h2>A Size Two Header</h2>

###A Size Three Header###

<h3>A Size Three Header</h3>

####A Size Four Header####

<h4>A Size Four Header</h4>

#####A Size Five Header#####

<h5>A Size Five Header</h5>

######A Size Six Header######

<h6>A Size Six Header</h6>

If you need to use some of those horrible bullet point lists, beloved of Word document monkeys, you can do that in Markdown too. Just put each item on a separate line and insert an asterisk followed by a space at the start, if you want a bullet point [ie. unordered] list and a number plus full stop and space, if you want a numbered [ie. ordered] list. Like so:

Unordered list:

* dog
* cat
* albatross

gives you

dog
cat
albatross

Ordered list:

1. dog
2. cat
3. albatross

gives you

dog
cat
albatross

If you need to embed images, or add links [handy when you’re composing a blog post, or otherwise generating text for use on the web], Markdown can do that too. The syntax is slightly more clunky here but not too onerous [and should be pretty familiar to anyone who’s ever edited an article on Wikipedia:

To make a normal link, just enclose the text which you want to make into a link in square brackets and then immediately follow this with the actual link URL in normal brackets. So:

[Click here for the beeb](http://bbc.co.uk) gives you this: Click here for the beeb

The syntax for embedding images is similar, with the addition of an exclamation mark at the start. In the case of an image, the text in the square brackets is optional [though you still need the brackets]. If supplied, that text will become a caption under the image.

No caption:

![](http://www.throup.org.uk/images/doctor_who/bbc_1986.png)

Caption:

![Look at this luvverly pic](http://www.throup.org.uk/images/doctor_who/bbc_1986.png)

Well, there’s a quick run through on the basics of Markdown syntax. As you can see, it’s pretty simple and, I reckon, a lot easier to knock out than working with a clunky word-processor. But you might still be wondering what’s the point. Why learn this [admittedly simple] syntax, when we can just use fugly old Word anyway? Well, here are a few benefits:

Accessibility --Since Markdown is just plain text with asterisks, hashes etc added in, you can write it in any text editor. You don’t need no ‘steenking’ office suite. Markdown files can be saved with a .txt extension, so any app which can read text files can open them. Compare that with Microsoft Office, where different versions can’t even open other versions of Word documents, never mind word-processor documents from other office suites, such as iWork or Open Office.

Re-usability --Since a Markdown file is just plain text, it doesn’t have all the formatting crud embedded in it that proprietary word-processor documents do. Therefore it can easily be converted or output into different formats. Byword , the markdown editor I’m using to compose this post [yes I will come onto software in a minute!] allows me to export what I’m writing here as either HTML, or a nicely formatted up PDF. Daedalus , another one I use also does PDF and HTML but, in addition, allows you to export your Markdown documents as ePub format, which is the most widely used eBook format. Not bad eh? a web-page, a PDF, or an eBook, all from the one document --which can be created or edited in any text editor.

OK. I’ve already waffled on a lot longer than I meant to, but let’s wind this up with a quick look at some nice software apps, which make working with Markdown even easier:

Byword

This is my favourite Markdown editor. It comes in OSX and iOS flavours. so you can use it on your mac and your iPhone or iPad. Since it also integrates with Dropbox, you can work on your Byword docs on any of your Apple gadgets. You can get the iOS app on offer for £1,99 at the moment and [seeing as its a universal app] that means you get both the iPhone and iPad versions for that. The OSX version is £6,99 at the time of writing.

Byword, running on my iPad. Note the extra bar it adds above the keypad, offering easy access to things like asterisks and brackets[although, for some weird reason, not to the hash symbol]. You can also swipe the bar left and right to reveal other tools, such as word count, image embed, etc:

Byword has a preview markdown* button, which is handy for showing you that your document is going to look like you intended:

The Markdown preview. Yes, I did remember the image syntax properly, after all!