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 asterisks1, like this: **bold**
creates a bold word. Italicized text is created by using single asterisks1, like this: *italics*
makes italics. 2
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:
- You can wrap an internet address in square brackets and place empty parentheses after it:
[http://www.google.com]
http://google.com - You can wrap a word in square brackets with the address after it in parentheses:
[google](http://google.com)
google - You can create a named link that can be used in more than one place in the text:
[google][goog]
google- 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
- 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.
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-dent3 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 line4. Markdown takes care of numbering the list appropriately when it renders the document:
- First
- Second
- First Sub item
- Second Sub item
- 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 on5.
##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:
##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!
##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:
- [Original Markdown]
- [Github-flavored Markdown]
- [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:
- Footnotes8,
- 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
-
Yes, you can use
***three asterisks***
to create bold italics. ↩ -
if that's a word. ↩
-
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. ↩ -
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. ↩ -
Taken from the MultiMarkdown Composer screen shot on the Mac App Store. ↩
-
I guess it depends on the type of parties you go to… ↩
-
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.