A MultiMarkdown Primer that uses as many of the features of MMD that I could think of. The only real purpose of this is as a quick way to find just about any MMD syntax you want and see how it's done. Note that this is MULTIMarkdown, not vanilla markdown or GFM.

Multimarkdown_Primer.md

Title: A MultiMarkdown Primer Author: Nate Dickson Date: Tuesday, December 18, 2012

#What Is Markdown? Markdown is a way to semantically format your text instead of stylistically formatting it. Markdown uses a set of simple and (somewhat) meaningful marks to set enrich plain text files in a way that makes sense to both humans and computers. Humans can create and style a markdown document, and then use software to render that document in any of a number of formats, depending on what is required. Markdown excels and creating HTML documents, PDF's, ![latex] documents, and other formats.

#How Do You Use It? Markdown documents are plain text files, nothing more. You use Markdown files the way you would any other text file, with simple, easy-to-remember formatting that allows it to be turned into other formats as required.

##How Does That Work? All Markdown formatting is accomplished through adding a few punctuation marks to plain text. For example, bold text is produced by wrapping a your text in double asterisks¹, like this: **bold** creates a bold word. Italicized text is created by using single asterisks¹, like this: *italics* makes italics. ²

Put a blank line between paragraphs to create, well, paragraphs. Markdown will handle all the tags for you, but not (and this is the good part) the styling. You can style the output however you want. There are a number of other marks that can be used as well, as discussed in the next section.

#Syntax!

No demo would be complete without a lot of contrived examples of using the syntax. So here they are! ##Links Links can be made in a number of ways:

1. You can wrap an internet address in square brackets and place empty parentheses after it: [http://www.google.com] http://google.com
2. You can wrap a word in square brackets with the address after it in parentheses: [google](http://google.com) google
3. You can create a named link that can be used in more than one place in the text: [google][goog] google
   1. You can also create a named link that has its own title, so you just include it in square brackets and an empty set of square brackets after it. This will leave the reference name, but will give your link a title attribute. [goog][] goog

All three (or four) of these methods will produce a link to Google.com

##Lists

unordered lists are created by placing an asterisk and a space at the beginning of a line:

• something
• Another thing
  • If you indent by one tab you can create a sub-item
• And then you can out-dent³ again to go back to the main list, just as you would expect.

Ordered Lists are created by placing 1. at the beginning of the line⁴. Markdown takes care of numbering the list appropriately when it renders the document:

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

##Headings

Headings are created by placing a number of # symbols at the beginning of a line. A single # is a top-level heading, ## is a second level heading and so on⁵.

##Images

Images in Markdown in much the same way that you would include a named link, except you put an exclamation point before the reference: ![gruber-image][] becomes this: ![gruber-image][] scary, huh?

##Pre-Formatted Text

We will probably never use this on my current site, but there are two ways to create pre-formatted text:

• Indent the text by one tab with no mark before it:

    I am pre-formatted text!
  

• wrap the text in back ticks: This is pre formatted!

##Block Quotes

Block quotes are easy: put a > before each line of text (which really means each paragraph:

>To be, or not to be, that is the ADVENTURE! become this:

To be, or not to be, that is the ADVENTURE!

--Ryan Q. North

##Tables

Tables are a [MultiMarkdown][] feature, and again, probably one that we will never use on our site, but they are relatively easy to set up and modify:

[All Kinds of Table Formatting][sampleTable]

Header	Row	Up	Here
Left Aligned	Centered	Regular (controlled by the style of your page)	Right Aligned
	Really looooooong Cell
Regular	Width	Cells	Across

You can also define a table somewhere in your text, then link to it elsewhere, like this: [Crayon Table][]

It should be noted that "relatively easy" doesn't mean "actually easy". They're still pretty messy, they generate less-than-optimized code, and they take far longer to render than any other element I've seen so far.

[Awesome Crayon Table][Crayon Table]

Features 6	MultiMarkdown	Crayons
Melts in warm places	No	Yes
Mistakes can be easily fixed	Yes	No
Easy to copy documents for friends	Yes	No
Fun at parties	No7	Sure?
Minimum markup for maximum Quality?	Yes	No

#Different Types of Markdown

There are three main types of Markdown:

1. [Original Markdown]
2. [Github-flavored Markdown]
3. [MultiMarkdown]

They each have their own strengths.

[Markdown Flavor Comparison][flavorCompare]

Type of Markdown	Created by	Pros	Cons
Original	John Gruber	most supported	Fewest Features
Github Markdown	Github	Best support for code, some enhanced features	Lacking text-based features of MMD
MultiMarkdown	Fletcher T. Penny	Best support for advanced formatting	Not as well supported as original markdown.

##Original Markdown Created by John Gruber in 2003(ish) original markdown was quickly picked up by a lot of tech writers worldwide as an easy way to format text without messing around with tags. It's also a useful substitute to the pseudo-standard rich text format (rtf) documents that have been used for years. As this is the oldest and most well-known version of Markdown it's also the most well supported, and there are libraries in just about every programming language that will convert markdown into HTML or other formatted text types. Unfortunately, most libraries will either extend or slightly twist their markdown formatting to enable more enhanced features.

The last canonical update to the Markdown specification was in 2004.

##Github-Flavored Markdown GFM is newer, but as it was created by Github it is geared toward creating documentation for code, not creating general-purpose websites. Pretty much everything that is written anywhere on GitHub's site is written in GFM, from their wiki pages to their blog pages to their home pages. GFM excels at support for code snippets, even allowing you to specify the language of the code snippet so that your syntax highlighter knows what keywords mean what.

Support for GFM outside of GitHub's website is scant, but growing. There are ruby and javascript libraries that support GFM, but they are sporadically maintained.

##MultiMarkdown MMD is around the same age as GFM, is actively maintained by its creator, and is described as a "superset" of regular Markdown. That is, it follows all original markdown rules, but adds support for a number of more advanced features.

Designed for writers of long scientific or prose documents rather than for code documentation, MMD adds a ton of features, most of which we would never use on our site:

• Footnotes⁸,
• Internal links
• Tables
• Citation support
• Metadata
• Definitions

Even with these new features, MMD attempts to stay true to the slim, human readable, and simple nature of original markdown. This document was created using MultiMarkdown.

[gruber-image]: http://www.geek.com/wp-content/uploads/2010/02/John-Gruber-portrait-by-George-Del-Barrio.jpg height=150px

[latex]: http://upload.wikimedia.org/wikipedia/commons/thumb/9/92/LaTeX_logo.svg/200px-LaTeX_logo.svg.png width=50px

Footnotes

1. or underscores. ↩ ↩²

2. Yes, you can use ***three asterisks*** to create bold italics. ↩

3. if that's a word. ↩

4. you can also number them 1. 2. 3. etc., but it's easier to maintain if you always use 1. because then you can move lines etc. without re-numbering. ↩

5. Well, there is another way that uses two lines for first and second level headings, but it reverts to the pound-symbol method for <h3> and below, so there's really no reason to use it. Ever. ↩

6. Taken from the MultiMarkdown Composer screen shot on the Mac App Store. ↩

7. I guess it depends on the type of parties you go to… ↩

8. I love footnotes. You may have noticed. This is part of why I like MMD so much. ↩

This file renders almost correctly on this page, but to actually render it correctly you need to use a real MultiMarkdown renderer.

Out of curiousity, where did you get your data that GFM and MMD are around the same age? According to Wikipedia, Github wasn't even founded until 2008 - did GFM predate Github?

As for rendering MMD on the Github site, some of the pieces to enable that are starting to exist, but need to be brought together:

fletcher/peg-multimarkdown#141

Fletcher,

My apologies, I didn't do the research to make that comment. When did you create MMD? I'll update this to reflect the truth instead of my blithe assumptions.