Gareth Redfern developer, cyclist & coffee lover

A Clients Guide To Using Markdown Instead Of Word

Posted by Gareth Redfern
Category: general Tags: markdown

Why Use Markdown Over A Word Processor

The main advantage is that all the correct formatting will be in place to enable your content to be read correctly by both humans and search engines. Many word-processors will add hidden characters to your content which ordinarily do not cause an issue until you cut and paste the content into your Content Management System (CMS). These hidden characters can cause unwanted line breaks and formatting issues which ideally should be avoided. Some CMS’s now have a feature which allow you to write markdown in the editor such as Statamic, which is really handy for keeping your workflow streamlined.

Below are some helpful examples of the most frequently used formatting options. Please note the # symbol on a Mac computer is created by holding down alt or shift (depending on your keyboard’s region settings) and the number 3 on your keyboard. For a more detailed outline of the formatting options you can visit the developers website


Use a hash symbol followed by a space before your heading: (closing #’s are optional), the number of #’s denotes the heading level:

# Header 1 #

## Header 2 ##

### Header 3 ###

#### Header 4 ####

##### Header 5 #####

###### Header 6 ######

Phrase Emphasis

*italic* **bold**

Links can be created by putting the word(s) you would like to display as the link in square brackets, then wrapping the link url between brackets, titles are optional but should have quotes around them.

An [example]( "Title")


Copy the format below and change the “alt text” for a short description of your image and change the image file path (between brackets) for the path to the image you are going to use, titles are optional but should have quotes around them.

![alt text](/path/img.jpg "Title")


List can be ordered or unordered and are simple to create by either using a number followed by a period and then a space (for ordered lists) or one of the three options - an asterisks, minus sign, plus sign followed by a space for unordered lists.

Ordered Lists

1. First ordered list item
2. Another item
  * Unordered sub-list

1. First ordered list item
  1. Ordered sub-list
2. And another item

Unordered Lists

* Unordered list can use asterisks
- Or minuses
+ Or pluses


Sometimes you may want to put a quote in your copy, this can be done by adding a right angle bracket followed by a space before the quote.

> Email-style angle brackets

> are used for blockquotes.

> > And, they can be nested.

> #### Headers in blockquotes


> * You can quote a list.

> * Etc.

Horizontal Rules

Three or more dashes or asterisks can be used to create a horizontal rule.


* * *

- - - -

Manual Line Breaks

End a line with two or more spaces to force a new line to start.

Roses are red,
Violets are blue.


Whilst this may be a new concept to follow at first what you should find is that you will be able to focus on your writing much more. There are some fantastic distraction free text editors (listed below) which are great for working with Markdown. When you hand off your content to your web designer/developer it will be in a format which can be easily transferred to your site. If you are using a CMS which provides you with a Markdown editor then you can create this content directly in the CMS itself or just cut and paste from your text editor.