Markdown

Introduction

Markdown is a plain text formatting tool that converts plain text to HTML. All descriptions in GitHub are written using GitHub Flavored Markdown (GFM), which is an extension of Standard Markdown (SM). Familiarity with GFM allows you to write more readable and structured descriptions for documentation/reporting issues/pull requests. In this document, we will just cover some of the basics of SM.

Headings

Headings must be preceded by one or more # symbols. These are equivalent to the <h> tag in HTML; # = <h1>, ## = <h2>, etc. Adding more # results in smaller headings (i.e. more is less).

# Largest 
##  Second Largest
...
##### Fifth Largest

Output:

Largest

Second Largest

...

Fifth Largest

### Text Styling

You can style text by wrapping it with either a * or _. Double wrapping results in bold text and single wrapping in italic text.

*Italic*
_Italic_
**Bold**
__Bold__

It is also possible to strike through text by embedding it in ~~ two tildes ~~, e.g. strikethrough.

Lists

You can create unordered lists by preceding list items with either a * or -.

* Item 1
* Item 2

- Item 1
- Item 2

You can create ordered lists by preceding list items with an integer followed by a full stop.

1. Item 1
2. Item 2

Note that lists can be nested by indenting with TWO spaces.

1. Item 1
  * Boo
    * Hoo
2. Item 2
  1. Foo
    * Bar
      * Baz
  2. Qux
    1. Quux
    2. xyzzy

Paragraphs

Separating one or more lines of text by one or more blank lines results in a paragraph.

foo.....bar.....baz......

qux....quux.....xyzzy......

Quotes

You can indicate quotes (blocks) with a >.

A wise man once said:
> In a world without fences and walls, who needs Gates and Windows?

Formatting

You can format special text (e.g. code) by using backticks `. A single backtick allows you to inline code, and a three backticks ``` allows you to create code blocks.

Tables

Tables are a part of GitHub's extension of standard Markdown (GFM). You can create tables by separating each header cell by at least three dashes ---. You can also use vertical pipes for readability and colons for alignment.

| Description   | Alignment    |Blah      | 
| ------------- |-------------:|:--------:|
| col 1 is      |left-aligned  |Foo       |
| col 2 is      |right-aligned |Bar       |
| col 3 is      |centered      |Baz       |

Description	Alignment	Blah
col 1 is	left-aligned	Foo
col 2 is	right-aligned	Bar
col 3 is	centered	Baz

Links

You can create links either by in-lining or referencing the desired link (hover to see the title):

![UKDS](http://www.esds.ac.uk/images/ukds_symbol.gif "Inline Logo")
![UKDS][Logo]
[Logo]: http://www.esds.ac.uk/images/ukds_symbol.gif "Referenced Logo"

Both produce:

HTML

It is also possible to embed raw HTML in Markdown. For example:

<h1> Heading </h1>
<em> Bold Text </em>
<dl>
  <dt>Coffee</dt>
  <dd>Americano</dd>
  <dd>Flat White</dd>
  <dd>Latte</dd>
  <dt>Tea</dt>
  <dd>English Breakfast</dd>
  <dd>Earl Grey</dd>
  <dd>Ceylon</dd>
</dl> 

produces

Heading

Bold Text

Coffee

Americano

Flat White

Latte

Tea

English Breakfast

Earl Grey

Ceylon

Mentions

It is possible to notify a team/user to view a comment by preceding the name by the @ symbol. For example, to mention the UK Data Archive in a comment, we can type @ukda.