A beginner’s guide to writing Markdown

Markdown is an easy way to write for the web. It’s simple: you write in normal English, and your web team can put it straight online as proper web code, or HTML. Easy! You’ll need to know how to do a heading and sub-heading if you’re writing for SEO at all. And you might want to know how to do bold, italics and links. If you learn one thing, make it headlines.

How to write headings in Markdown

Headlines (or headings) are as easy as putting a hash sign (#) at the start. On a mac, that’s alt-3. Like this: # A simple guide to Markdown Pretty simple, right? This keeps it perfectly readable, and makes the line stand out as a heading at the top of the page. If you’re writing for SEO, this is an important place to put your main keyword for the page. If you write more than 200 or 300 words, you might want to start breaking up the text with sub headings. Here’s how to do a sub-heading in Markdown: ## How to write headings in Markdown Simple again! We just write two hash signs. If one of these sub-sections get too long, we just write a third layer of sub-heading with three hashes, and so on. You can go all the way to six layers, but by that point I recommend spreading your content across multiple pages. Usually three layers of headings is plenty. Web developers would call the main heading an ‘h1’ and the sub-heading an ‘h2’. Maybe you’ve heard of them. The amazing thing is, your simple easy-to-read Markdown will convert straight into the same code these web developers use. But yours is easier for non-tech teammates to read, and many developers love writing in Markdown too. Let’s move on to another basic:

How to write in Bold and Italics in Markdown

To write in italics, just wrap a word or sentence in one star, like this. To write in *italics*, just wrap a word or sentence in one star, like this. To write in bold, just wrap a word or sentence in two stars, like this. To write in **bold**, just wrap a word or sentence in two stars. You can do bold and italics on the same word with three stars, but that would look terrible. Don’t do that.

How to write lists in Markdown

Lists are so easy. Just write a dash at the start of each line, or a number at the start of each line for a numbered list. They’ll come out as proper bullet or numbered lists when your content appears online. - Bulleted list 1. Numbered list

How to write web links in Markdown

That’s enough for you to go and write great content in Markdown. Of course, writing for the web usually involves including links. Links are still pretty easy, but not quite as elegant as headings or formatting. If this looks too much to take on right now, you can always add links in your web editor like Word Press. Let’s say I want to link to my Twitter profile, like this: Tom Davenport’s Twitter Page First we wrap the text in square brackets: [Tom Davenport's Twitter Page] Then we put the web address in brackets straight after the closing square bracket, with no space: [Tom Davenport's Twitter Page](http://www.tomdavenport.co.uk) Some people mix up which way the brackets go. I remember it like this: the square brackets look like a picture frame. I’m framing the text as a link, the following with the web address in brackets as an afterthought. You can do this with a link mid-sentence, like this link to the guy that invented Markdown, or on its own line as above. They all work the same.

Adding a title to your Markdown links

If you’re writing for SEO, I recommend one extra tweak to your links. You know how hovering over a link for a few seconds usually shows a little text window to say what the title of the next page is? Try it on the link above if you want to see an example. This is called a title, and it’s good practice to include this on every link you write. It’s good for the user, and good for SEO. To add a title to your link in Markdown, put it after your link in quote-marks, but stay inside the brackets: [Tom Davenport's Twitter Page](http://www.tomdavenport.co.uk "Tom Davenport on Twitter")

Markdown resources

You can get started with Markdown in any text editor you want. If you are serious about putting Markdown into your regular workflow, here are some extra resources worth looking at.

Markdown text editors

Microsoft Word is not the only text editor in the world. Here’s some popular alternatives which specialise in writing for Markdown, and have options to magically export in code.

• [Byword] is my current favourite. It has a quick-look preview so you can see how your text looks on-screen to a reader.
• [iA Writer] was my favourite for years. Really beautiful minimal interface with no distractions. In the end, it was too minimal for my taste, but it’s worth a look and there’s a pro version with extra tools to study your writing style.

For team collaboration I strongly recommend Draftin. This is a web-based tool with powerful features that make a web content project much easier. You can write in Markdown, then get team mates to add or edit the text. You can choose to approve or reject these edits one click at a time, and every version is saved so you can scroll back at any time. That’s the tip of the iceberg, so do check out the full Draftin feature list.