Markdown Primer
Many of the TUAW writers (and readers!) are fans of John Gruber's Markdown, so we tend to review both iOS and Mac apps that support Markdown.
If you don't know what Markdown is or how to use it, those articles will probably leave you scratching your head (at best) or angry/frustrated wondering why we're talking about Markdown again.
What is Markdown?
Markdown is a way to write plain text files that can easily be converted into another format. Most often Markdown is converted to HTML to write web pages, but it's also possible to use it to create other formats such as PDF, RTF, LaTeX and much more.
Why use Markdown?
Markdown offers a few basic features.
"Plain txt 4eva!"
Plain text will live forever. OK, maybe not forever, but if you look back over the history of computers, it's clear that popular file formats come and go. If you go back into my personal file archives, you'll find a bunch of files that are all stored in WordPerfect files. Of course when I switched to Mac, I stopped using WordPerfect and switched to MSWord (.doc) and then to Pages.
The problem with each of those formats (not to mention all of the others I could mention) is that they change, and many are not natively supported by different computers. Plain text files, on the other hand, work everywhere. Other than some differences in the way file endings are encoded, you can open a plain text file without issue on Mac, Windows and Linux computers, no matter how old or new your computer or operating system is.
Easier to read
HTML source is messy to read, and doesn't mean much if you don't know HTML and if it isn't laid out nicely. Since Markdown works off some basic formatting principles, reading "raw" Markdown should make sense even the people who don't "know" Markdown.
Easier to write
HTML isn't all that difficult to write by hand for basic formatting and text markup, but Markdown is easier. Writing <b>bold</b> isn't hard, but **bold** is easier. Using *italics* is easier than <i>italics</i>, and ***bold and italics*** is much easier than <strong><em>bold and italics</em></strong>.
Links are also easier. A standard Markdown link begins with the link text in [ ] followed by the URL in ( ), so This is a link to [TUAW](http://tuaw.com) gives you "This is a link to TUAW."
Mix with HTML when needed
One of the biggest boons to using Markdown for writing HTML is that you don't have to choose between using "just HTML" or "just Markdown" for any given document. If you want to use some of Markdown's features mixed with HTML, go right ahead. They are designed to work together.
Markdown For Beginners
Showing emphasis:
*italic*
**bold**
***bold and italic***
(You can use _ in place of * in those examples. I tend to use underscores for italics and asterisks for bold or bold and italics together)
Links and Paragraphs
For links, the words you want to show go in [ ] and the URL goes in ( )
So [this is a link to TUAW](http://tuaw.com).
And if you just want to include a URL and have it "clickable," just put angle brackets around it <http://tuaw.com>.
Use blank lines for paragraphs breaks <p>.
Use three spaces at the end of a line to force a linebreak <br> without a blank line.
Lists and Blocks
Start a line with a number followed by a period (.) to make a numbered list (OL), such as "1. This is the first item in a list."
Note: If you don't want Markdown to take over numbering your lists, use ")" instead of "." For example, "1) This is the first item in a list which won't be automatically changed by Markdown."
Start a line with an (*) for an unordered/bulleted list (UL)
Start a line with right angle bracket (>) to blockquote. Increase the number of > to increase blockquote levels.
Start a line with a TAB to make a code block. Wrap text in backticks (`) to make it inline code.
Headers
Start a line with a hash mark (#) to make an H1 (i.e. # This is a Header).
Start a line with a double-hash (##) to make an H2 (i.e. ## This is a secondary header).
When using # to start a line, you can put # at the end of the line also, but you don't have to, and some Markdown parsers seem to fail on realizing that the # at the end of the line is an option, so I've stopped using it.
Markdown for Intermediate users
The above covers probably 90 percent of what I use Markdown for, but there is more.
Reference Style Links
What Johh Gruber calls "reference-style links" in the Markdown Basics and syntax pages allows you to mark links in the text and then put the URLs somewhere else. For example, instead of [This is a link to TUAW][http://tuaw.com] I could write [This is a link to TUAW][TUAW] where the first part [This is a link to TUAW] is the link text and the second part [TUAW] tells Markdown to look for the URL elsewhere. Then you would put a reference link somewhere else, usually at the bottom of the document, like this:
[TUAW]: http://tuaw.com
That's not bad, but I much prefer using "implicit link names" where you leave the second set of brackets empty. For example: This is a link to [TUAW][] which says to Markdown "use whatever text is in the first set of brackets for the reference link. It would still match to
[TUAW]: http://tuaw.com
elsewhere.
Images
There is also a syntax for images:
I tend not to use that very often, because the image is just dropped into the text, without any width or height, which may lead to the page reflowing/jumping around. If you want to float an image over to the right of your paragraph (like most of the images at the beginning of TUAW articles), you'll need to use HTML, not Markdown. You can, however, use HTML combined with Markdown, so if you know the tags, feel free to drop an actual <img> in with styles or classes applied.
Other Versions Of Markdown
There are a few more features that I haven't mentioned, which you can find on the official Markdown page, but there are also other "implementations" of Markdown, including the extremely popular MultiMarkdown and PHP Markdown Extra, which add extra features onto Markdown's syntax. There are other "Markdown, but also with..." implementations out there. Each one seems to come about when someone has been using Markdown for a while and then decides that they need some additional feature that isn't a part of the official Markdown specification, such as footnotes.
Sometimes you might not even realize that you're using one of these "Markdown+" services. For example, Tumblr uses Markdown, but they also will automatically make URLs clickable even if they are not wrapped in angle brackets, and Tumblr also supports MultiMarkdown's format for footnotes, but they just list it as "Markdown."
The danger, of course, is that if you get used to using one of these "Markdown+" formats, you may later find that it isn't interoperable with a different app that supports Markdown. So if you are, for example, writing a book using Scrivener with MultiMarkdown, obviously you hope that your footnotes are going to work in 2015.
But the point is that even if all of the Markdown parsers in the world are gone in 2015, you will still be able to read your text in Markdown format in any text editor, which will work much better than trying to read one of my old WordPerfect files (which is just text) in a text editor:
My thanks to Doc Rock for reminding me of the Markdown cheat sheet I wrote a few months ago.
