• Format text without using "what you see is what you get" editing tools
• Use simple symbols like asterisks, dashes, etc. for formatting
• A program turns it into its final form, but it's intended to be readable and intuitive
• Still, some syntax (e.g., links, images) takes some getting used to!
• Plus, there are a number of different flavors:
  • The original markdown
  • GitHub's flavor
  • This page describes basic markdown + GitHub's extensions, but calls out the latter

Write text normally. Single linebreaks are ignored. Hence, if you write:

O to realize space!
The plenteousness of all, that there are no bounds,
To emerge and be of the sky, of the sun and moon and flying
  clouds, as one with them.

It becomes:

O to realize space! The plenteousness of all, that there are no bounds, To emerge and be of the sky, of the sun and moon and flying clouds, as one with them.

In situations like this, when you want to force a linebreak, end the line with two spaces ().

O to realize space!  
The plenteousness of all, that there are no bounds,  
To emerge and be of the sky, of the sun and moon and flying  
  clouds, as one with them.  

Here we are also using HTML's "non-breaking space" ( ) to force indentation of hte last line. This becomes:

O to realize space!
The plenteousness of all, that there are no bounds,
To emerge and be of the sky, of the sun and moon and flying
  clouds, as one with them.

Emphasize something: *single stars*

Really emphasize something: **double stars**

Didn't mean it: ~~double tildes~~ (GitHub flavor)

You can also use _underscores_ instead of stars.

Quote someone:

> The crucial operating premise of the Free Software Movement as a 
> revolutionary politic is: proof of concept plus running code. 
* Eben Moglen

becomes:

The crucial operating premise of the Free Software Movement as a revolutionary politic is: proof of concept plus running code.

• Eben Moglen

Use # for headlines, number of # indicates header depth, e.g.

# First level
## Second level
### Third level
#### Fourth level

becomes:

First level

Second level

Third level

Fourth level

Use dashes, asterisks or numbers to make list items, indent with two spaces:

* Take over the world
* ???
  - We need a plan
    1. Make a plan
    2. **Execute it**

becomes:

• Take over the world
• ???
  • We need a plan
    1. Make a plan
    2. Execute it

For numbered lists, you don't need to write the numbers yourself -- in fact, your numbers are ignored:

1. First item
24. Second item
1. Third item

becomes:

1. First item
2. Second item
3. Third item

Links and media intentionally use very similar syntax.

Links: [some link text](some URL)

Media: ![some alt text](some URL)

The "alt(ernative) text" is displayed/read out loud for users who can't view the media file, and should be descriptive of the media file's contents.

Examples:

[Defective By Design](http://defectivebydesign.org)

!["Authors Against DRM" logo](https://static.fsf.org/dbd/AADl.png)

becomes:

Defective By Design

When you just want to use plain URLs and email addresses, you can surround them with <angle brackets>. In GitHub style, you don't need the angle brackets for URLs -- in vanilla markdown, you do.

My name: Grover Cleveland  
My email address: <president@whitehouse.gov>  
My homepage: https://www.whitehouse.gov/

becomes:

My name: Grover Cleveland
My email address: president@whitehouse.gov
My homepage: https://www.whitehouse.gov/

A single backtic marks inline code segments:

This is some text with `<code>` in it.

becomes:

This is some text with <code> in it.

Lines indented with four spaces are interpreted as code blocks. In GitHub style, you can achieve the same by using four backtics before and after the code block:

````
var l = 0.1 + 0.2;
console.log('Mind the floating point: '+l);
````

becomes:

var l = 0.1 + 0.2;
console.log('Mind the floating point: '+l);

In GitHub style, you can specify the programming language (for syntax highlighting) after the backtics, like so:

````rust
// Import (via `use`) the `fmt` module to make it available.
use std::fmt;
````

becomes:

// Import (via `use`) the `fmt` module to make it available.
use std::fmt;

You can use arbitrary identifiers within text to label and re-use links, like so:

In 2000, *Salon* [described][cite1] [NetHack][] as "one of the finest 
gaming experiences the computing world has to offer." 

[1]: http://archive.salon.com/tech/feature/2000/01/27/nethack/
[NetHack]: http://www.nethack.org/

This becomes:

In 2000, Salon described NetHack as "one of the finest gaming experiences the computing world has to offer."

So, source readers will see a nicely enumerated list, and if you keep referring to the same site, you only have to update it in one place. Note how in the second link, the link text and link label are identical, so we can omit the identifier parameter.

Markdown also supports generating the "title" attribute for links, which is displayed by most browsers as a tooltip you see when hovering over the link. Just type it after the URL, separated by a space, enclosed in quotation marks:

[This link is mysterious](https://debian.org/ "The universal operating system"). 
Hover over it to get a hint.

becomes:

This link is mysterious. Hover over it to get a hint.

Use dashes and pipes to construct simple tables (remember the pipe has to go all the way through for each column!):

Year | Potato produce (thousands of tons) *estimate*
-----|----------------------------------------------
1845 | 11000
1847 | 2000
1849 | 4000
1851 | 5000

becomes: