While major writing projects requiring lots of research, sometimes I just want to write up several paragraphs in an article without a lot of fussing about. Text editors are perfect for this, while also guaranteeing, unlike Word, Pages, or even more open formats, maximum future readablity and recoverability. Unfortunately, going back in to properly add links, italicize or quote text, etc., can be a pain.
Thus was born Markdown. Markdown is both a plain-text syntax for tagging text for web/formatted output and a program of the same name that converts text in the markdown syntax to valid HTML. Since the formatting and syntax use conventions already long common in emails, it’s very easy to mark up the text, and text formatted this way is highly readable even as plain text.
Since I don’t feel like breaking out a massive writing tool like Open/Libre Office or Scrivener every time I want to write up a few paragraphs, and since I absolutely hate going back after the fact to format everything in even the best WYSIWYG implementations when I could do it from the keyboard as I type, I really appreciate the ease of use.
I also appreciate the fact that it’s widely available. While blogger doesn’t directly support it, it’s fairly easily added to WordPress, and is available for Posterous and Squarespace.
So here’s my cheat sheet that I keep in Emacs when I need a reference. Most of it is paraphrased from the original, and further details or nuance are linked to on a section-by-section basis to Gruber’s original spec:
Markdown reference:
You’ll note the headers for each section link to the respective section in Gruber’s syntax page for more information on the available options and nuances.
Block Elements
A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines
This is a new paragraph.
To FORCE a
newline,
use two
spaces.
Headers
Two types.
This is H1 (with ===== underneath)
====================================
This is H1 (with ===== underneath)
This is H2 (With ------ underneath)
-------------------------------------
This is H2 (With —— underneath)
Alternately, you can use ‘#’
# One '#' for h1
One ‘#’ for h1
## Two '##''s for h2
Two ‘##”s for h2
Three '###' for h3, and so forth.
Three ‘###’ for h3, and so forth.
Blockquoting
Markdown uses email-style “>” characters for blockquoting. They can be
nested by adding additional levels of ‘>’. They can also contain other
markdown elements (headers, code blocks, etc…
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
>
>> Inset second level.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
Inset second level.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
Lists
Markdown supports ordered (numbered) and unordered (bulleted) lists.
Unordered Lists
Unordered lists use asterisks, pluses, and hyphens — interchangably — as list markers:
- Item a
- Item b
- Item c
- Item a
- Item b
- Item c
Ordered Lists
Ordered lists use numbers followed by PERIODS. Order is irrelevant.
1. Dog
2. Cat
3. Kids
- Dog
- Cat
- Kids
List items separated by a space have the content of the <li> wrapped
in a <p> paragraph tag.
Code Blocks
To produce a code block in Markdown, simply indent every line of the
block by at least 4 spaces or 1 tab. For example:
This is a code block.
A code block continues until it reaches a line that is not indented
(or the end of the article).
HTML in a code block is converted to entities, and Markdown syntax is
NOT processed within a code block.
Horizontal Rules
You can produce a horizontal rule tag (<hr />) by placing three or
more hyphens, asterisks, or underscores on a line by themselves. If
you wish, you may use spaces between the hyphens or asterisks.
---
***
___
Span Elements
Links
Inline or reference. In both styles, the link text is delimited by
[square brackets]. See the original
syntax for a
more thorough explanation of reference-style links.
This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.
Reference-style links
[This is linked] [id1] to something
[id1]: http://www.midknightgallery.com/ "Midknight Gallery home Page"
This is linked to something
Also, a reference can be implicitly identified by the linked content
[The Midknight Gallery][] is a great site.
[The Midknight Gallery]: http://www.midknightgallery.com/ "Home"
The Midknight Gallery is a great site.
Emphasis
**Bold**
Bold
*Emphasis*
Emphasis
Emphasis can be used in the middle of a word:
Crap*tac*ular.
Craptacular.
Backslash to escape literal asterix’s like this: \*.
Span of Code
Wrap a span of code within a paragraph with backtick quotes (`)
To include a literal backtick character within a code span, you can
use multiple backticks as the opening and closing delimiters:
``There is a literal backtick (`) here.``
Images
Inline image syntax looks like this:
Reference-style image syntax looks like this:
![Alt text][id]
Followed by the same syntax as reference links:
[id]: url/to/image "Optional title attribute"
Miscellaneous
Backslash Escapes
Markdown provides backslash escapes for the following characters:
\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark
Automatic Links
Simply surround the URL or email address with angle brackets.
<http://example.com/>
Markdown will turn this into:
<a href="http://example.com/">http://example.com/</a>