man thinking

Markdown Quick Reference

Markdown is a very simple text formatting language that is expressed in plain text and which can be converted by a markdown processor into HTML. The name is a play on the fact that HTML is markup language. It is often used in web applications where we want to give a user of a web site a way of creating formatted text without having to go to the complexity of authoring HTML, for example in a discussion forum. It was created in 2004 by John Gruber and Aaron Swartz

You might wonder why we need something like markdown. After all, wasn't the idea of markup languages like HTML and XML that we would never actually edit the markup directly? We were going to use WYSIWYG (What-you-see-is-what-you-get) editors that would make editing HTML easy and we could save to the web. It didn't pan out that way; for some reason WYSIWYG editors, like most code generators, always seem to end up creating complex code that is difficult to follow and work with when you inevitably need to work with it by hand. We also had JavaScript HTML editors that gave us buttons and drop downs to highlight text and so on, but again they introduce complexity somehow. Markdown is just such a simple and elegant solution where the annotated text is readable and simple and most of the time goes through the processor unchanged. For example if you write a paragraph followed by a blank line, it renders as an HTML P tag. And where you need something markdown doesn't supply you can just use normal HTML and the processor will pass it through. It gets the job done.

The only slight problem I find is that I forget a few of the markdown syntax rules. It really is simple enough to remember, except that for a moment you might forget which way the square and round brackets go for a link, or how to get italics. Markdown flavours vary, but most of the basic features should work in all of them, so here's a quick reference.

# Heading
## Subheading
### Subsubheading
#### etc.
Blank line -> new paragraph

Two spaces at end of line -> line break (BR tag)
*italic* _italic_ (EM tag)
**bold** __bold__ (STRONG tag)
~~strikethrough~~ (DEL tag)
`unformatted text` (back-tick for inline CODE tag)
    unformatted text (indent four spaces or a tab)
    more unformatted text (block within PRE and CODE tags)
--- (horizontal rule - HR tag)

* bullet
* list

1. numbered
2. list

> block quote (BLOCKQUOTE tag)
> block quote second paragraph

[link text](
[link text]( "title attribute")
![image alt text](/images/myimage)
![image alt text](/images/myimage "image description for title attribute")
[![link text](](/images/myimage)
[![link text](](/images/myimage "image description for title attribute")
<> (shortcut link syntax where link text is the link itself

Simple | HTML | Table  (use colon instead of space to set alignment)
----- |:---:| ---
1 | 2 | 3
4 | 5 | 6

If you want literal characters without being converted use the backslash escape, e.g. \*not italic, just asterisks\*. And don't forget to escape the < character (&lt;) to avoid it being interpreted as HTML.

It helps to know what HTML tags are being rendered when it comes to working with CSS to style the resulting HTML markup.