Markdown

The majority of internet content is displayed using HyperText Markup Language (HTML), which tells internet browsers how to identify and display different forms of text. Since browsers do not work like word processors and cannot inherently process 'rich text' (bold, italics, etc), content needs to be annotated to say 'this bit is italic', or 'this is a link'.

HTML takes the form of starting and ending tags, which identify portions of text that require special treatment. For example:

I want <b>this bit of my text</b> to be in bold, but <i>this bit here</i> italicised.

will be displayed by a browser as:

I want this bit of my text to be in bold, but this bit here italicised.

However, learning HTML can be time-consuming, and sometimes frustrating! This is where Markdown comes in. It replaces the HTML tag system with something a bit more intuitive. In Markdown, the above example would take the form:

I want **this bit of my text** to be in bold, but _this bit here_ italicised.

A quick rundown of the main Markdown syntax is presented below, followed by some explanatory images.

Markdown Syntax

Paragraphs and Line-breaks

  • To create a new paragraph, simply separate text by a blank line (ie. 2 carriage returns).
  • A line break (ie. 1 carriage return) can be added by adding 2 blank spaces at the end of a line. You may continue writing on the next line. This will only be recognised as a line break after text – ie. you cannot put 2 spaces on multiple consecutive lines to create multiple line breaks. Instead, use:

  • The <br /> HTML tag forces a line break, and can be used multiple times consecutively.

Text Formatting

Bold and italic text can be defined by using:

Some text, a **bold** word and an _italic_ word.

...which will produce:

Some text, a bold word and an italic word.

Headers

Five levels of (sub-)heading are possible by using hashes:

# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5

The first header is defined by the 'Title' box on most content create/edit screens - so don't use this when writing your content unless you want another title-sized heading! The second level heading should suffice for most sub-heading needs.

Bullet/Number Lists

Bullet lists are created by using * and 1. Note: you must ensure that a space is included between the '*' or '1.' and the bullet text.

* List item 1
* List item 2

1. List item 1
2. List item 2

...will create:

  • List item 1
  • List item 2
  1. List item 1
  2. List item 2

Links

To insert a link to another page on the website, simply enclose the text you wish to turn into a link in square brackets, and specify the URL directly afterwards in normal brackets:

I would like [this specific bit](/about) to be a link to an 'About' page.

For ease, you can use shortened URLs. Normally the URL for the 'About' page would be 'http://www.example.org/about' - but we can use just the '/about' part.

Email addresses and external websites should be turned into links automatically by Markdown without the need for any brackets. However, if you do need to specify an external link using the brackets method, use:

I would like [this specific bit](http://www.york.ac.uk) to be a link to the University of York

The preceding 'http://' is necessary for the link to function, and MUST be included when specifying external websites.

info [at] microwine.eu

X