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 Six Header

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

##### A Size Five Header

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

#### A Size Four Header

````###A Size Three Header###````

### A Size Three Header

````##A Size Two Header##````

## A Size Two Header

````#A Size One Header#````

# A Size One Header

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

  4. dog

  5. cat

  6. 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]( 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:


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:


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!

Choice of export formats. HTML, PDF, or copy HTML –handy for pasting into blog posts.

### [Daedalus]( Daedalus is my second choice Markdown editor. It’s available for iOS only [so no integration with OSX] for £2,99 at the time of writing. It also integrates with Dropbox, to help you move your stuff between iPhone and iPad. Daedalus Touch, to give it its full name is arguably more polished looking than Byword. Daedalus’s creators make a big thing about doing away with folders and files. Instead Daedalus organises your creations into Stacks and Sheets of paper [ie. folders and files]. But, credit where it’s due, it does look nice and slick. Here’s the Stacks view, showing all my Stacks [ie. folders] of Sheets [ie. files]

Pinch or double-tap on a Stack and it opens up to reveal the Sheets inside. Pinch or double-tap on a sheet to open it for editing:

Daedalus also adds a bar across the top of the keyboard, giving access to commonly used Markdown symbols. The buttons on the Daedalus bar act as popups, with more choices nested inside and are also customiseable:

Daedalus also has more export options than Byword:

And more preference settings:

As well as a built-in look-up function, for doing basic researching from within the interface. I haven’t used this yet though. It seems a bit gimmicky to me, when I can easily switch to a full-featured web browser and back

On the whole, I think Daedalus is the more elegant, better featured and slicker-looking app, but it has two major drawbacks which keep it second choice behind Byword for me. The first, I have already mentioned: Daedalus has no OSX version, so it’s not as integrated across all my gadgets as Byword. Secondly, Daedalus doesn’t offer a preview function, which seems like an unforgiveable oversight on the developers’ part. The only way to see what your Markdown looks like is to export it as a PDF, open that and then, if you need to make any changes, go back and edit the original –and then repeat the whole process again. It’s a horribly clunky way to go about things, for an app which is otherwise so well thought out.

Well, there you have it folks. A brief introduction to the nerdy-but-accessible world of Markdown. If you hate word-processors as much as I do, why not give it a go. You might like it.

Scroll to Top