I have recently fallen in love with Markdown. It’s a hybrid of coding and writing that allows you to quickly style your text without having to move your hands off the keyboard or know any HTML.
Markdown works by using simple patterns and special characters within text. You can enter these while typing and barely slow down your pace. You can type this way in any app without needing formatting capabilities, but you need an app or plugin that understands Markdown in order to convert your writing into richly formatted text. I’ll recommend some tools below.
Markdown is already natively supported on sites like GitHub and Reddit.
Here are my top five features of Markdown and how it helps me write articles and podcast show notes faster.
1. Fast headlines
Markdown uses the pound/hash sign to indicate the level of a heading. Starting a paragraph with
# makes that paragraph a “Heading 1,” just as if you had selected that from a toolbar or used the
<h1> HTML tag. Heading 2 would be
##, Heading 3 would be
###, and so on. (Side note, most blog posts and articles on the web should use Heading 2 and down instead of Heading 1 and down. Heading 1 is usually reserved for the post/article title.)
\# Heading 1
## Heading 2
### Heading 3
2. Easy lists
Making bullet-point or numbered lists can become frustrating in many editors. It’s especially complicated when you want to reorder your list and you start cutting/copying and pasting. (This sometimes results in accidentally nested lists.)
Making lists with Markdown is easy! Just start your lines with a hyphen or asterisk and don’t separate your list items with blank lines, and you’ll get a bullet-point list.
– Item 1
– Item 2
* Item 3
- Item 1
- Item 2
- Item 3
I personally prefer using the hyphen, because asterisks can do two additional things (more on that in a moment) and a hyphen is quicker to type than a asterisk.
Magic really starts to happen with numbered lists. Start your lines with
1. or any other number, and the list will become a numbered list. You don’t even have to use the right numbers or the right order!
1. Item 1
1. Item 2
5. Item 3
3. Item 4
2. Item 5
- Item 1
- Item 2
- Item 3
- Item 4
- Item 5
3. Simple code snippets
If you do any kind of technical writing, you may have a need to insert small pieces of code. Some editors will let you type this in plain text, but others will try to process the code or hide it altogether.
But with Markdown, you can display your code in a monospaced font and not worry about its being processed or hidden.
To enter a small, inline piece of code, surround the code with a backtick ([crayon-5d869373143fe037472718-i/], usually on the same key as the tilde).
To make a code block, indent each line with one tab or four spaces. But many Markdown apps and plugins share some elements from GitHub-Flavored Markdown, including letting you put a line of three backticks before and after the block of code.
<h2>Block of code</h2>
<p>With multiple lines</p>
<h2>Block of code</h2>
<p>With multiple lines</p>
Markdown doesn’t offer any special code highlighting, just a plain monospaced font. I like the Crayon Syntax Highlighter plugin for more detailed code examples on WordPress, like I used in How to disable Disqus on custom post types.
Markdown may not play nicely with code-highlighting plugins
In writing this post, I had huge problems working with the Markdown code snippet examples and any example blocks. The problem is a conflict between Markdown and Crayon Syntax Highlighter plugin. Both of them wanted to use backticks, and both of them had different ways of displays blocks of code. So my code block examples above are actually made with Crayon Syntax Highlighter, since I need to keep it activated.
Backticks and other special symbols on mobile devices
Even with most Bluetooth keyboards, the backtick is not usually an available character to type. To work around this, I suggest copying the backtick character and making a keyboard replacement code for it. I type
.bt on my iPad and get a backtick inserted. I’ll write more about this in the future.
4. Quick formatting
Even without headlines and lists, you’ve probably found the need to at least bold or italicize text. Again, Markdown makes this easy.
For bold, surround your words with double-asterisks (
**) or double-underscores (
This is **bold** becomes “This is bold.”
For italics, surround your words with either single asterisks or underscores.
This is _italic_, and _this is, too_!
This is italic, and this is, too!
I like to use underscores for italics and double-asterisks for bold, as this is similar to how Google+ formats text. But Google+ uses single asterisks, instead of double, for bold.
Note that Markdown will be smart enough to understand partial italics with punctuation, but also smart enough to not italicize code-style uses of underscores, like
5. Manageable hyperlinks
Hyperlinks can be the hardest pieces of text formatting to manage. A typical text-editor would have you select the text to hyperlink, click a button, and paste a URL; or press a button to create the hyperlink, enter your text, and paste the URL. It gets really complicated if you want to add text to the beginning or end of the hyperlink and want that text included or not included in the hyperlink. This would commonly be punctuation (which isn’t usually included in hyperlinks when it’s at the beginning or end) or adding extra words like “the” to be included in the clickable text.
To make a hyperlink, surround the text you want to link with square brackets (
]) and follow that with the URL in parentheses (
[Learn how to podcast](http://TheAudacitytoPodcast.com/)
You can also add title text to your links insert the parenthesis with a space, double quotation mark, the title, and then another double quotation mark.
[Learn how to podcast](http://TheAudacitytoPodcast.com/ "The Audacity to Podcast")
Becomes (hover your mouse over the link):
You can do even fancier things with links, like reference them just like footnotes, which is great for repeat links, or links you need to add later.
[my favorite search engine][Google]
[Daniel J. Lewis][myblog]
Markdown plugins for WordPress
I’ve tested two different plugins that enable Markdown for WordPress. Try both of these and see which approach you prefer.
This WordPress.com-connected plugin has many features and it’s now a lot easier to manage. Jetpack includes a module for Markdown, which maintains your standard WordPress Visual and Text editors, but allows you to type Markdown in either editor.
Jetpack’s Markdown module allows me to write Markdown in the mobile WordPress apps (this post was first drafted with the WordPress app on my iPad).
I prefer Jetpack’s Markdown module, but I have four small problems with it.
- I can’t see any hierarchy to my text unless I preview the draft post. This makes following my show notes on The Audacity to Podcast a little harder.
- Code snippets become a pain in the visual editor. When I type HTML, such as
<div>in the visual editor, WordPress turns the
>, respectively, in the source Text editor and in the final post. This means I have to either write in the Text mode or switch to it for code snippets.
- Lists require a little more thinking in the visual editor. By default, pressing Enter in the Visual editor will create a new paragraph, not just a new line. But Markdown lists must not be separated with blank lines, so I have to press Shift-Enter in order to insert a line break. This only applies in the Visual editor. In the Text editor, I would have to press Enter twice to make a new paragraph.
Ghost characters in output. Sometimes, for no apparent reason, “Â” will randomly appear where a space should be. Retyping the space usually fixes it. This has messed up regular spaces as well as Markdown syntax.(This turns out to be a problem with my WordPress setup, not Jetpack or Markdown.)
This plugin serves one purpose: Markdown. It replaces the Visual and Text editors with a Markdown editor and previews your Markdown formatting just below your editor. WP-Markdown can be enabled in comments and bbPress posts.
While WP-Markdown seems to give more control, I have some deal-breaking problems with it.
- Forced to use the Visual editor. This means I have to be either writing everything in Markdown, or else not use this plugin for Markdown. I can’t progressively use Markdown in my writing – it’s all or nothing. Jetpack’s Markdown module, on the other hand, lets me mix Markdown with my use of the formatting buttons in the visual editor, or mix Markdown with real HTML in the Text editor.
- Disabled friendly interfaces of the visual editor. Inserting images, managing formatting, and using plugins gets almost impossible when the Visual editor is disabled.
Other Markdown apps
Expect to see more support for Markdown in popular apps in the future (I’m hoping for it in Evernote!). But here are a few apps that I know support Markdown on different platforms.
- Day One for Mac and Day One for iOS for journalling
- Drafts for iOS for making quick notes or writing whole articles on iOS – it can even save to Evernote and other services
- Atom text editor for code-editing and Markdown writing with a live preview, free for Mac OS X, Microsoft Windows, and Linux
Learn more about Markdown
There’s so much more to Markdown, like blockquotes, images, automatic links, and horizontal lines. Read about Markdown basics and syntax to get more power!
How has Markdown saved you time? What are your favorite tools for writing in Markdown?