An Introduction to Markdown

If you blog, write notes, write articles or books, or any form of writing with formatted text you might want to consider using Markdown.

John Gruber who created Markdown a decade ago describes it this way:

Markdown is a plain text formatting syntax that allows you to write in an text editor and then have it converted to valid XHTML (or HTML).

What this means is that you can write formatted text using any text editor and then via a software tool have it converted to an HTML document. As the use of Markdown has grown there are tools for converting it to many other forms including PDF. One source document can be converted to multiple formats.

I use Markdown as part of my daily workflow to write notes, help documents, blog posts, and pretty much any writing workflow. The main reason I like Markdown is that I can write even heavily formatted documents in plain text and still have the plain text version be very readable. Often I don’t even convert these documents since I can easily read them as is. While I could certainly write them using HTML tags that really reduces the readability and it can quickly be difficult to read in plain text form. Once I have written a document in Markdown I can quickly convert it into the medium of choice. I use it to quickly create ebooks from Markdown documents along with converting online web pages into Markdown for reference later.

To give you an example of how easy Markdown is to use, here are some examples.

By using one or more Number signs # I can quickly write headers and use > to create blockquotes.

For example:

# Header 2

> This is an example of a blockquote

Header 2

This is an example of a blockquote

Bold and italics can be accomplished using:

    This item is **bold** and this is using _italics_.

Becomes:

This item is bold and this is using italics

Want to write lists?

+ This is item one
    * Indented list item
+ This is item two
+ This is item three

1. This is a numeric list item one
2. This is a numeric list item two
3. This is a numeric list item three

Becomes:

• This is item one
  • Indented list item
• This is item two
• This is item three

And:

1. This is a numeric list item one
2. This is a numeric list item two

   a. Another

   b. Another

3. This is a numeric list item three

But what I really love about Markdown is how I can insert links.

Now it is easy to do inline links to create a link with the text you give it or a naked link like using angle brackets.

[Some Site](http://www.ewtn.com)

<http://www.ewtn.com>

Becomes:

Some Site

http://www.ewtn.com

This is fairly readable, much better than <a href=“http://www.ewtn”>Some Site</a>, still I find reference links even better.

With a reference link I can name a link and then put the actual URLs at the end of the document. This makes reading the plain text version much easier and you have alllk your links in one place and you don’t have to repeat them when using the same reference.

Here is a link to [Some site][ewtn] along with a link to [Catholic Answers][catholic]. Plus here is a link to [my blog][jester] and another link to to [Catholic Answers][catholic].

[ewtn]: http://www.ewtn.com
[catholic]: http://www.catholic.com
[jester]: http://www.splendoroftruth.com/curtjester

Becomes:

Here is a link to Some site along with a link to Catholic Answers. Plus here is a link to my blog and another link to to Catholic Answers.

Reference links make my life so much easier. When I post the Weekly Francis I write it in Markdown and I have all the URLs listed at the bottom of my document for both readability and be be able so easily spot malformed URLs.

Images can also be inserted via inline or reference links.

![](http://www.splendoroftruth.com/curtjester/wp-content/uploads/2014/04/vatican_top_button.jpg)

and

![][uparrow]

[uparrow]: http://www.splendoroftruth.com/curtjester/wp-content/uploads/2014/04/vatican_top_button.jpg

Becomes:

and

Now this post is not intended to be a full Markdown tutorial. Just one to show you the simplicity and power of Markdown and why it might be something you could use.

Since Markdown was originally released a decade ago the syntax has remained stable. Still there are other flavors that have added onto the original Markdown standard such as MultiMarkdown and a new standardization format called CommonMark. While all these variants support the original syntax they also add support for other features such as tables and more advanced formatting features. You can also use straight HTML format in Markdown documents along with Markdown syntax.

So once you have written a document using Markdown syntax you might wonder just exactly how you convert it to XHTML or other format. There are a growing number of editors that allow you to write in Markdown and preview it live and then convert it. On Mac OSX I happen to use Marked 2 app because it is super-powerful allowing me to use any text editor I want and get a live preview of the document along with ability to convert into multiple formats. If you come to like Markdown and have a Mac Marked 2 at $13.99 on the Mac App Store is worth every penny.

While you can use any text editor to create these documents it can be useful to use an editor specifically created using Markdown more like a traditional word processor. Here are some suggestions. Not an exhaustive list by any means as this is a growing field.

• OSX
  • MacDown – A free an open source version for the Mac.
  • MultiMarkdown Composer A paid app, bu they have a demo version.
  • Marked 2 which I previously mentioned.
  • Ulysses III a writer’s tool for long-form documents including novels which can be used with Markdown and other markup languages.
• Windows
  • MarkdownPad. This is the only one I have used on the Windows side and it has a free and a pro version.
• Linux
  • No experience regarding Markdown editors on Linux, but they are available. If you have suggestions let me know.
• OSX and Windows
  • Scriviner 2 Another professional app for writers that is very powerful and can use Markdown syntax. Lots of management features if you are writing anything from a research paper to the Great American Novel.
  • HastyScribe A command line program to convert Markdown Documents to self-contained HTML pages.
  • Sublime Text 3: Powerful text editor that has packages supporting Markdown. $70.
  • Atom.IO: A free open source text editor with both support for Markdown formatting and previewing. Also very powerful and similar to Sublime Text 3 and created by GitHub.

In addition many websites already allow the use of Markdown such as reddit, wordpress.com, and Squarespace along with countless sites used by programmers such as StackOverflow and GitHub.

The amazing thing about Markdown is that I could write this post in plain text and have no problem viewing it as plain text. I will use Marked 2 to create the HTML which I will paste into my WordPress blog. I keep this original post in a plain text document which I store in Dropbox. I wrote this in Sublime Text 3 which is my text editor of choice.

Markdown References

Original Markdown

MultiMarkdown

CommonMark

Markdown Tutorial

Heck Yes Markdown Converts a web site from HTML to Markdown. Can also format document using Readabililty

MDwiki: Create a Wiki site using Markdown using a single document to launch it.

Jekyll: A framework for creating websites and blogs using Markdown and generating a static website.