Introduction In the last few months I’ve been working on a website where I was encouraged to use Markdown for writing content. While Markdown has been around for quite some time, I haven’t used it, and have plodded on writing full markup. This is usually a tedious chore, especially for long pages of content, even with just basic formatting.
Markdown to the rescue!
What is Markdown? Markdown was introduced by
John Gruber as an alternative to writing full HTML. Markdown syntax is simple, and can be converted into HTML via software tools. It is used primarily to simplify the writing and formatting of text; as such, it allows for most common use cases but does not cater to all. Where some specific HTML does not have a Markdown equivalent, the HTML can be written directly as needed. One driver behind Markdown is readability. Full HTML can quickly become difficult to read, since content can get drowned in a sea of angle brackets. Markdown symbols are simple and generally stay out of the way; once the syntax is understood, they convey the intended meaning rather clearly. Quoted from Markdown: Syntax:
The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Paragraphs are marked by two consecutive new lines, which finish the previous paragraph, if any, and begin a new one. A line break is inserted by typing two spaces at the end of a line followed by a single new line. Text formatting is done by surrounding the given text by particular characters:
<em>emphasis</em>renders emphasized text, while
<strong>strong</strong>renders strong text. Three consecutive underscores (
___) render a horizontal rule. And
> quoted textrenders a blockquote. There’s more to Markdown than these brief examples, but they do show how simple it can be. Note that a Markdown character can be excluded from conversion by prefixing it with a single backslash (“), as follows:
#2(the escaped version leading to the generated output) Note that in the following case, two backslashes are needed, one for each of the leading asterisks:
**strong**=> **strong** In the case of a heading, say an
h2, a single backslash at the start of the line seems to be enough to prevent conversion, possibly since the symbols need to be at the start of the line to work as intended.
Some Sample Snippets Following are a number of commonly-used Markdown snippets. Emphasized text:
*emphasis*, _emphasis_ Strong text: **strong**, __strong__ Headings: # heading level 1 ## heading level 2 ### heading level 3 #### heading level 4 ##### heading level 5 ###### heading level 6 Inline code blocks for use within e.g. paragraphs `code` Block-level code samples, usually for longer listings, indented with 4 spaces or a tab. The block-level snippets in this post are written using this syntax: code block Horizontal rule (three consecutive underscores): ___ Blockquote: > blockquote Hyperlink: [a link to Google](http://google.com) Unordered list: * list item * list item * list item Ordered list: 1. list item 2. list item 3. list item This is not a complete list, and is just scratching the surface. As stated earlier, these are what I consider the most common uses. Here is
a full listing of Markdown syntax.
Useful Tools Being a simple syntax, Markdown can be written by even a basic text editor. There are tools available to speed the process of writing as well as viewing the converted result. I mention three such tools below.
MarkPad is a Metro-style app, first made available earlier this year. It is rather minimal, which to me is fine for the purpose. The appearance is very tidy, and the interface stays out of the way, There is a floating toolbar that appears when text is selected, and offers buttons to format text or create links. The left pane is the raw Markdown and text, while the right pane shows the result.
MarkPad is developed on GitHub and appears to be actively maintained.
MarkdownPad is a more conventional Windows app, with the standard window chrome and toolbar. The premise is the same is MarkPad, however. Like MarkPad, the left pane is the Markdown view and the right pane is the converted view. The toolbar has buttons for common formatting and linking features, but those are hardly needed when writing Markdown, as the syntax is so simple.
It’s good to have choices, and mine is MarkPad, mostly for the simpler interface. Oddly though, it doesn’t have a search function, which MarkdownPad does.
The above editors are useful for writing Markdown locally, but there will be a point where content needs to go online. Since WordPress is my web tool of choice, I started using the
WP-Markdown plugin. Installing the plugin doesn’t add a distinct menu item for configuration; the plugin’s options are added to the bottom of the Settings -> Writing administration section. There are a small number of settings to choose from, none very complicated.
Once the plugin is configured, it can be seen in action by creating (or editing) an existing post or page. Entering text in the content box will cause a “markdown view” box to appear immediately below with a live preview. Saving the entry and viewing it will show the rendered version in all its glory. In fact, this very post was written using Markdown – see for yourself the result!
Interestingly, the plugin extracts inline link references and lists them at the bottom, as can be done in Markdown, and references each from the corresponding linked text: 1: http://daringfireball.net/projects/markdown/ 2: http://daringfireball.net/ 3: http://daringfireball.net/projects/markdown/syntax 4: http://code52.org/DownmarkerWPF/ 5: https://github.com/Code52/DownmarkerWPF 6: http://markdownpad.com/ 7: http://wordpress.org/extend/plugins/wp-markdown/ Link text referencing a link in the list:
[Markdown] [John Gruber] [Markdown: Syntax] ...