Markdown Guide

Introduction

Markdown is a text formatting language which is designed to be simple, powerful and easy to read/edit. We are using it for content addition instead of plain HTML (which is not easy to read/edit).

Note: We are actually using a slight modification of Markdown, called Markdown Extra.

You can use HTML inside Markdown, but it should be avoided except for rare cases.

The full syntax of Markdown can be found on the official Markdown syntax guide, and changes that we're using are listed on the Markdown extra site. If you've never used Markdown before, you should read through those pages before adding content. The following should only be used as a quick cheat sheet. In the event that this page and the official documentation disagrees, follow the official documentation (and notify someone to change fix this page, if appropriate).

Important: Always preview!

Cheat Sheet

Paragraphs

A paragraph is Markdown is one or more lines of text, separated by one or more blank lines. This means that you can manually wrap text if you prefer and it will still be one paragraph as long as you don't leave blank lines.

Do not indent the first line of paragraphs.

Both

Hi, I am a paragraph.

and

Hi, I
am a paragraph.

yield

Hi, I am a paragraph.

Lists

Unordered lists are created with *, +, or - at the beginning of lines. They're equivalent as far as the resulting list goes (pick one and stick with it within the same list of course).

Ordered (numbered) lists are created with numbers followed by periods at the start of lines. The numbers don't matter to markdown, but always start with one and go up, as a matter of style.

* Alpha
* Beta
* Gamma

or

+ Alpha
+ Beta
+ Gamma

or

- Alpha
- Beta
- Gamma

show as

  • Alpha
  • Beta
  • Gamma
1. Steal underpants
1. ???
1. Profit

shows as

  1. Steal underpants.
  2. ???
  3. Profit

Emphasized text

You can emphasize text by surrounding it by asterisks, or underlines. One asterisk/underline on each side leads to italicized text (em tag in HTML), and two on each side leads to bolded (strong tag in HTML).

  • *aoeuhtns* -> aoeuhtns
  • _aoeuhtns_ -> aoeuhtns
  • **aoeuhtns** -> aoeuhtns
  • __aoeuhtns__ -> aoeuhtns

Links can be inserted with the following format: [Link Text](http://address.example.com "Title"). Title is optional, but try to use them if it makes sense.

[An example](http://example.com "Everything you desire")

yields: An example

Reference style links can be written like [Link Text][reference], and then at any point in the same document (on its own line), [reference]: http://address.example.com "Optional Title"

With reference style links, if the reference is the same as the link text, the reference can be omitted.

[Reference Style][reference style]

or

[Reference Style][]

and then elsewhere in the document on its own line

[reference style]: http://example.com "A reference style link"

yields: Reference Style

Images

Use HTML for images, check the content author guide for instructions on how to automatically insert the right HTML, as well as for styling help.

Headers

Headers come in two styles, underlined with ====== (for biggest header), or ------ (for second biggest), or prefixed with a number of #s, from one to five. Higher numbers are subheaders.

Header One
==========

or

# Header One

yields

Header One

## Header Two

or

Header Two
----------

yields

Header Two

Important: Read the style guide for correct header usage. Do not just use them to make big text, they should be section headings.

Blockquotes

Blocks of quoted text are created by starting each quoted line with right angle brackets ">", like you'll sometimes see in emails.

> This is some quoted gunk
> and this is more

yields

This is some quoted gunk and this is more

Code blocks

If you indent each line of a block of text by at least four spaces (or one tab), it will be output as a preformatted code block (usually used for discussing programming or markup source code). One level of indent is automatically removed (four spaces or one tab).

Alternatively, you can surround code blocks by a line of tildes (three or more).

~~~~~~~~~~
<p>A literal block of html</p>
~~~~~~~~~~

or

    <p>A literal block of html</p>

output as

<p>A literal block of html</p>

Horizontal rules

Horizontal rules can be created with a line containing only asterisks, hyphens, or underscores (three or more).

------------------------------------

yields


Tables

You can do tables by separating the table headings from table content with hyphens, and separating table columns with pipe characters, like so:

First Column | Second Column
-------------|--------------
Some content | Hello
Some more    | Hello again
And yet more | Huzzah!

yields

First Column Second Column
Some content Hello
Some more Hello again
And yet more Huzzah!

This can get difficult for large tables, so you are allowed to use HTML tables. Be sure to use all of the semantic tags that are appropriate however, such as thead, caption, tbody, etc.

Backslash escapes

Since Markdown gives special meaning to some characters, if you want to literally include one of those characters in a place where it would otherwise have special meaning, add a backslash (\) before it.

Converted HTML entities

In HTML you must escape certain characters such as &, <, and > using &amp; &lt; and &gt; instead. That is not necessary in Markdown, and will be done automatically for you. You still can input them in the long form, it's just not required for the common ones.

Inline HTML

You can use HTML inside Markdown texts, but avoid it wherever possible. While a full page of HTML is technically valid Markdown, it will not be accepted by the moderators under normal circumstances.

See the Markdown Extra site for inline HTML rules if you need it. This supersedes the rules stated in the Markdown syntax guide (but still check the Markdown syntax guide, as it's more complete).

And more!

This is not a full list. If you need something more exotic, or to see the full rules governing any syntax, check the official documentation: Markdown and Markdown Extra.