Markdown and Writing

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
  1. Dog
  2. Cat
  3. 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:

![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")

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>