Table Of Contents
There’s a wealth of articles about Markdown on the Internet, but many of the resources are not useful for how to get started using and laying Markdown syntax. So you might be wondering: What is Markdown? What is its purpose? And how do I use it? Let’s try to answer that together.
What Is Markdown?
Markdown is essentially a syntax language for formatting text as you write. It’s fast, and built for people who write for the web.
Formatting text in Microsoft Word, and other traditional text editors, can take a while. For example, when you want to format the title header of a document, you select the title and apply the menu item, Format > Font > Bold, or apply the header preset style. Similar menu items are used for italicizing selected text, creating a numbered or bulleted list of items, and adding a URL link.
Additionally, the formatting done in programs like Word use a lot of code for formatting – code that can mess up articles intended to be published online.
Some people, knowing this, use HTML formatting directly instead. For example, to bold text in HTML, you wrap the selected text using this syntax code> <b>Use these tags to bold text</b>. If you want to use a header in HTML, you use what is called header tags: <h2>Title of Document</h2>, so that the title style is applied.
Markdown is another way to format text – faster than typing HTML yourself, and better for web publication than using Word. It also includes special tags or syntax for formatting text. For example, to bold selected text using Markdown you wrap the text in four asterisks like this: **Use asterisks to bold text**. Those tags format the text in an application that supports Markdown.
Markdown is faster, and has less of a learning curve, than HTML. Markdown, and what is called MultiMarkdown, can be used for common text formatting, including italicizing text, blocking quotes, adding various header levels, typing ordered and unordered lists, and adding strikethroughs. It can also be used for adding inline URLs, email links, inline images, footnotes and footnote links, and simple tables.
Why Use Markdown?
If you’re not a web designer or developer you may be asking: why should I learn Markdown when I can use menu shortcuts in a text editor to format text? That, Sherlock, is the same question I had.
In today’s digital spheres we increasingly find ourselves typing in different applications, or even mostly on the Internet. We are no longer limited to traditional text editors like Microsoft Word or Apple’s TextEdit. We now have access to a range of writing applications, including online text editors and writing apps for mobile devices. When we format a document in a text editor we want to make sure the formatting language we use in one piece of software can be supported in other text editors.
We can either use Markdown in a dedicated Markdown editor like Mou, Simplenote, or MarkdownPad 2, or we can apply Markdown in a plain-text editor like Apple’s TextEdit or Notepad for Windows, and then export it to a native Markdown editor. Markdown documents can be exported to PDFs, HTML and other text applications.
Markdown can be a useful tool for producing clean, professional looking research papers, memos, email messages, or blog posts without the hassle of remembering lots of HTML tags, which are difficult to use and read when applied to text documents or webpages.
Markdown is easy to apply as you type, so if you’re typing using a writing app for the iPad, or an online text editor, you can add Markdown syntax as you write your document. In fact, many of the popular text editors for the iPad and iPhone support Markdown instead of traditional formatting tools. See chapter 6 for sample iOS, Android, and web applications that support Markdown.
While some writers, web developers and designers use Markdown and MultiMarkdown for all the documents and webpages they produce, you might only use it when writing in a favorite application or when writing blog posts. For example, I use Markdown mainly in the OS X and iOS Day One journal application, Ulysses for the Mac, and Byword for the iPad. Documents I format and produce in these applications export without a problem to PDF which is where most of my documents end up.
As you will see in the following tutorial sections, Markdown is relatively easy to learn. As you practice you using it, it will not be difficult to remember the syntax for applying it.
You can apply Markdown in any text editor, but you will also need a Markdown supported text editor that can read and “print” your applied Markdown formatting. For example, you can apply Markdown in an application like TextEdit or Notepad, but you can’t preview the Markdown formatting that you have applied in those applications. You need to export applied Markdown documents to applications like Marked, Ulysses, MarkdownPad 2, or to a Markdown web application like Dillinger. For the purposes of learning Markdown, I suggest you use one of many dedicated Markdown editors which you can be download for free.
Markdown supported applications can be used also to export your documents to PDF and HTML, and some editors will export to other applications on your iOS device, Mac or PC.
Because Markdown does not belong to any proprietary software program, the syntax you apply can be read many different desktop and mobile applications.
In the following sections of this guide, I introduce a step-by-step approach to learning Markdown. To follow along in the tutorials, you need one of three applications:
- StackEdit, a web application (Markable.in and Dellinger are two other web client options)
- Mou, a Mac OS X application
- MarkdownPad 2 for Windows.
These applications include both a text editor and a preview feature side-by-side, which means as you format text in Markdown you can automatically see the results.
Each of the above applications includes a Help file that explains Markdown. The Help document may be all you need to get started; however, the following tutorials will walk you through step-by-step for writing in Markdown and MultiMarkdown syntax.
Before we get started with the tutorials, the following section provides a description of the three Markdown editors to choose from.
StackEdit: Web Application
Most Markdown web applications include similar tools you need to write in Markdown. For the following tutorials I mainly use StackEdit because it includes a few time-saving menubar tools for quickly applying Markdown syntax. StackEdit also allows for syncing documents to your Dropbox or Google Drive account.
If you have already downloaded StackEdit, you will see a welcome document containing sample instructions for how to use Markdown. But to follow the tutorials in this guide, create a new document by clicking on the New Document icon in the menu bar. StackEdit is set up with a text editor on the left and a preview on the right. If you plan to use StackEdit for the tutorials, you can proceed to the next section.
Mou: Mac OS X
Mou is a straightforward Mac application. After you download and install Mou, a Help document should open (if not, you can open it in Help > Mou Help). The document will not be directly used for our tutorials, but I want you get an overview of how Mou is set up with a text editor on the left side and a preview on the right.
For our tutorials in the following sections, start a new blank project, File > New Project.
MarkdownPad 2: Windows
MarkdownPad 2 is a Windows text client similar to the above two applications. The free version of MarkdownPad is sufficient for getting started with learning Markdown, but you will need to upgrade to MarkdownPad Pro to unlock all its extra features, including Auto-Save, PDF export, and the built-in image uploader.
As with StackEdit and Mou, MarkdownPad opens with a Help document that lists all the Markdown syntax on the left side, and a preview on the right. For the purposes of the tutorials, create a new document (File > New).
Let’s Get Started
With a blank document opened in your chosen Markdown application, we are ready to get started. These tutorials explain, one at a time, the most frequently used Markdown and MultiMarkdown syntax (Headers, Bold and Italics, Ordered Lists, Blockquotes, Links and Email Links, Inline Images, Horizontal Line, Strikethrough, Footnotes, and Tables). For each tutorial I provide an example of exactly what to type, but if you prefer, you can use your own words and sentences. You’re going to find these tutorials a pretty easy ride.
I will first instruct you with what to type and then follow those instructions with any additional explanations you might need to know.
On the left side of the text editor type:
#Use Number Signs For Formatting Headers.
You should see on the preview side the Markdown syntax automatically applied.
Now hit the return key a couple of times and type (or copy and paste) the same title again, but add an additional “#”. The header gets smaller. The number sign doesn’t need to be right next to the first letter of the header. You can put a space between the number sign and the first letter – the effect will still be the same.
For a Level 1 header in Markdown, you can also type the “=“ key a couple of times under the header – it will have the same effect.
Bold and Italics
Now let’s move to applying the bold and italics formats. You can either start a new file or continue using the one you have already started.
Type the following in the editor:
Use asterisks to **bold** text.
Use underscore key to _italicize_ text.
Or use single asterisks to *italicize* text.
Again, the results should automatically show in the preview.
Practice with a few more sentences of your own.
Note: You may have already noticed in the application you’re using menu tools and keyboard shortcuts for quickly applying Markdown syntax. In the case of the bold format, you use Command+B or Control+B, and for italics you use Command+I or Control+I. In MarkdownPad and StackEdit, these same menu items are in the toolbar.
In Chapter 6, I also introduce automation applications and actions to apply syntax more quickly.
Ordered lists are pretty straightforward. If you’re using a Markdown editor, it will recognize that you’re creating a numbered lists and automatically format the space between the number, periods, and text accordingly.
Now hit the return key, and the next number should automatically appear. Add at least four items to your numbered list. To stop the numbers from appearing, hit the Return key again after the last item.
Then hit the Return key, wherein the editor should automatically add the next asterisk. Add three or four more items to your list.
Instead of asterisks, you can also use a dash followed by space.
Note: if for some reason you start off with a numbered list and you want to follow it up with unordered list, you will need to separate the two lists with header or sub-header item; otherwise, Markdown will not treat the next set of lists accordingly.
One of the easiest Markdown tags to use is the greater than key, “>”, for block quotes. I use it a lot in my Day One journal. Here’s how it works:
Copy and paste these two dummy paragraphs in the editor you’re using.
Cake lollipop tiramisu tootsie roll. Cookie cupcake macaroon jelly beans dessert tiramisu. Soufflé chocolate pudding donut halvah.
Pudding gummi bears jelly-o sweet roll chupa chups lollipop cake candy canes. Gummi bears muffin chocolate cake powder cheesecake. Tiramisu carrot cake fruitcake croissant halvah. Liquorice sweet ice cream cupcake soufflé toffee jujubes brownie dessert.
Make sure there’s a space between the two paragraphs.
Next, type the greater than key, “>”, right before the word, “Pudding,” in order to blockquote that paragraph.
Note: The style of the blockquote may be slightly different from editor to editor.
Email Address Link
Handling email links in Markdown is also pretty straightforward.
Copy and paste the following emailing address or use your own, and wrap it in angle brackets (< >), typically called greater than and less than symbols. See the results in the screenshot below.
Inline URL Links
Inline link works pretty much the same way.
Type the following sentence with the greater-than and less-than tags on each side of the URL.
This is an inline link, <http://makeuseof.com>, in which the URL is shown.
Copy and paste the following sentence:
This is an inline link, [MakeUseOf] (http://makeuseof.com), in which the URL is embedded.
Now add brackets on both sides of the anchor text, and parentheses around the URL, instead of using brackets.
The results should look like this:
Adding Inline Images
You can use Markdown to add inline images, but the link image must be posted and linked somewhere on the Internet, such as ImageShack.us.
Here’s how to set it up.
Copy and paste the following text and direct image link in the editor:
This the MakeUseOf logo:
Type this reference tag in front of the image link.
Note: The tag name can be anything that helps identify the image.
Be sure the parentheses are typed on each side of the image URL.
The results should look like this:
Horizontal lines are useful for breaking up the content in documents. You may have noticed that a horizontal line was used in the screenshot in the section on URL links. To add a horizontal line in Markdown, simply type three dashes where you want the line to appear.
Copy the two dummy paragraphs below into the editor:
Powder toffee apple pie apple pie tootsie roll I love croissant applicake. Gummies chocolate cake carrot cake gummi bears chocolate bar lemon drops. I love marshmallow chocolate bar carrot cake gummies wafer candy canes.
Gummies jelly-o jujubes cheesecake marzipan jelly beans toffee apple pie toffee. Chocolate jelly beans bear claw muffin oat cake. Dessert fruitcake danish halvah oat cake cookie. Lollipop gummies lollipop. Oat cake gummi bears dessert jujubes danish wafer applicake.
Type three or more dashes (- – -) between the paragraphs. You can also type three or more asterisks, but I find dashes are more associated with lines and thus easier to remember.
Hard Line Break
When you want to add a hard line break using Markdown, in some editors adding two or more spaces after the end of the line where you want to add the hard break should do the trick. Using HTML, this code is inserted between spaces: <br> </br>
Markdown documents are typically outputted to HTML, exported to PDF, opened in another application, or sent directly to a printer. As you learned in the previous tutorial sections, most Markdown applications you use will include a way to preview applied Markdown either as you type or in a separate preview window.
If you are looking for more control over the output of Markdown documents than what your current Markdown editor provides, you might be interested in the Mac application, Marked ($3.99).
Marked is not a text editor; instead, it contains features for supporting Markdown documents imported into it. See my full review of Marked.
Marked allows you open documents from your favorite text editor or Markdown text editor so that you can write content in the linked editor and use Marked for all the final Markdown formatting and layout.
Clicking the gear button on the bottom-right of the preview window provides access to other features including word, line, and character counts, readability statistics, visual word repetition, and the ability to copy the document to HTML, Rich Text, save it to PDF, HTML, RTF, or send it your printer.
Now we turn to tutorials for using MultiMarkdown, which is simply a subset of Markdown syntax. MultiMarkdown is a little more complex, but it’s especially useful for blogging and academic writing.
You may not use strikethroughs all that often, but they are easy to add using Markdown.
Type or copy and paste this sentence.
This is an example of strikethrough.
Add two squiggly characters (~~strikethrough~~), or what is technically called tildes, on both sides of the last word in the sentence. This method is easier than using the HTML code, <del>strikethrough</del>
Footnotes are typically used in academic papers, but they can also be useful in other documents in which a list references appear at the end of the document, instead embedding links in the body of the document.
Copy and paste the dummy paragraph text:
Cupcake ipsum dolor sit amet apple pie danish. Dessert jelly-o jelly beans lollipop jelly brownie tart. Powder bear claw marzipan unerdwear.com cheesecake muffin biscuit caramels. Chocolate cake tiramisu chupa chups brownie dessert pastry dragée tart sesame snaps. Cotton candy marzipan icing. Bear claw gingerbread lollipop. Unerdwear.com powder sesame snaps sesame snaps unerdwear.com dragée apple pie donut chocolate bar. Chocolate caramels gingerbread candy jujubes cookie marshmallow gummies soufflé.
Type the following marker at the end of the first sentence: [^1]. To type the caret key, use Shift + 6 or a Mac or Alt+94 on a Windows PC.
Type another marker [^2] after the last sentence of the pasted paragraph.
In our tutorial, we’re not using a long document, but go ahead and type the following footnote references under the paragraph, as if you were typing them at the end of a long document.
[^1]: Cupcake Ipsum is fun text.
[^2]: [Cupcake Ipsum](http://www.cupcakeipsum.com/#)
Each footnote must have a unique reference number, put into brackets followed by a colon.
After you add the colon to the reference numbers, the footnotes will become linkable. A horizontal line will automatically appear above the footnoted references.
Markdown can’t handle complex tables, but if you need to categorize content so it’s clean and presentable, MultiMarkdown has you covered.
Type the following titles for table, and separate each column with a vertical bar (|), or pipe.
Good Food | Bad Food
Next type multiple dashes under the titles, and add a vertical bar between them.
Good Food | Bad Food
——- | ———
Add items in each column by typing a vertical bar between column items. Note: the arrangement of words do not have to line up evenly. The Markdown editor will sort it all out.
Good Food | Bad Food
——– | ———
fruits | candy
carrots | potato chips
oily fish | fatty meat
Note: Markdown doesn’t allow for much control over spacing in your columns, and creating them using Markdown may be a little more challenging than creating tables using a word processor.
Some editors will not format tables with lined columns and rows, such is the case in the Mou editor. However, in the application Marked, the line and shaded formats are added.
As you learn how Markdown works and begin to use it, you will probably wonder if there is a way to add the syntax quickly without manually typing them. Yes, there are several tools, depending upon your needs and workflow, to use for applying Markdown.
You may have already noticed that the editor you worked with in the previous tutorial sections includes either keyboard shortcuts for applying Markdown syntax and/or a set of tools in the toolbar that you click and apply tags.
In Mou, the tools are under Actions in the menu bar. The menu bar shortcuts are similar to the formatting tools in Microsoft Word, except in the case of Markdown when you click on, for example, Command+B, it types four asterisks and inserts the cursor in the middle of them. There are also shortcuts for creating a strikethrough, URL link, hard line break, etc.
In the online Markdown editor, StackEdit, the syntax tools are conveniently placed in the toolbar so you can quickly apply a blockquote, link, a header, and so forth. The image link shortcut allows you to import image links directly to a photo in your Google+ Drive image library.
Similarly in MarkdownPad 2 for Windows, the toolbar includes all the basic syntax for creating a hyperlink, a blockquote, ordered and un-ordered lists, a horizontal rule, etc.
There are a few Mac automation programs (e.g. TextExpander, Keyboard Maestro and Automator) that can be used for quickly applying Markdown syntax. Explaining how to use Markdown actions and macros in these programs is too expansive for this guide to cover. But I do include links below to Markdown actions and workflows that you can import into these applications if you’re already using one or more them.
TextExpander and Keyboard Maestro
TextExpander (MUO review of TextExpander) is a Mac application that types snippets of text based on assigned abbreviations. It is a powerful tool that anyone who writes a lot should be using. It’s also useful for creating Markdown syntax. For example, I have a text expansion snippet that types the italic Markdown tags (**) and inserts the cursor in between the asterisks. It does this when I type the assigned shortcut, “88”, which is a character combination I rarely use for typing numbers. Another example: when I type “hht”, TextExpander quickly replaces the shortcut with a “#”. This snippet is useful when I’m not using a Markdown editor that includes the shortcut.
Keyboard Maestro (MUO review of Keyboard Maestro) is another automation application which is useful for applying Markdown. With Keyboard Maestro you can, for example, create a macro that will apply specified Markdown tags to selected text. Essentially, the macro cuts the selected text to the system clipboard, and then automatically pastes it with the specified syntax.
Micheal Schechter, over at A Better Mess, has posted a useful set of TextExpander Markdown snippets and Keyboard Maestro macros for download, as part for his article, “How a Lazy Person Writes In Markdown.” You can customize the snippets and macros to fit your workflow.
Markdown Services Tools
Another way to apply Markdown is using the Services Menu feature in OS X (read more on applying Markdown with the services menu). Developer Brett Terpstra has created a set of Automator workflows, saved as service tools, that apply Markdown syntax to a selected text in any application using the drop-down Services menu.
These workflows will only make sense if you are familiar with the Services and Automator workflows, but they are not difficult to learn. See my free PDF MUO Guide to Mac Automation for how use Automator.
The Mac App Store contains dozens of text editing applications, like Mou (one of the applications used for tutorial for this book), and most of which include live editors that show a preview of applied Markdown as you type.
There are also other text editors, such as Scrivener (MUO review), and the journal-writing app, Day One (MUO Reivew), which support Markdown, but many of them don’t include live preview. Applied Markdown in these applications is converted when the documents are saved or when the documents are exported to a supported format, such as PDF. In the case of Day One, the Markdown is converted when the journal entries are saved in the application.
Which text editor(s) you choose will ultimately be based on your needs and workflow. If you’re going to do a lot of writing in Markdown, you probably will want to download an editor with live preview.
Below I highlight a handful of editors that I’m familiar with or that have been reviewed on MakeUseOf.com.
All the following editors, unless otherwise noted, include menu bar and keyboard shortcuts for applying regularly used Markdown formatting, (e.g., bold, italics, lists) and a live built-in preview of applied Markdown. Documents created in these editors also allow for export to HTML, PDF, and RTF.
- Write App for iOS – Write App: A Beautiful iOS Text Editor With Markdown Support & Dozens of Actions
- Editorial for iPad – Editorial Brings Powerful Text Editing and Automation to iPad
- iA Writer – iA Writer for Mac & iOS: The Best Word Processor You’ve Never Used
- Drafts – Drafts: The Ultimate Notes App For The iPhone and iPad [iOS]
- Mou for Mac – Learn Markdown Using Mac Text Editor Mou
- Byword – Byword Offers Fullscreen Distraction-Free Writing Pleasure On Your Mac
- Marked – Stylize Your Markdown Documents With Marked for OS X
- Ulysses III – Ulysses III: A Clean Stylish Text Editor for Writing and Managing Documents
- MultiMarkdown Composer – MultiMarkdown Composer ($11.99) is one of the most advanced Markdown editors, with several built-in style sheets (e.g., plain text, eBook, Manuscript, Solarized) for formatting text and paragraph layout, as well additional, though limited, exporting capabilities for RTF, Microsoft Word, ePub and OPML.
- LightPaper – Write & Preview Markdown In Style With LightPaper [Android]
- Draft for Android – Draft: A High-Quality, No-Nonsense Way To Keep Notes On Android, With Full Dropbox Sync
Google Chrome and Online Editors
- Textdown – Looking For A Good Markdown Editor On Chrome? Try Your Writing On Textdown
- Markable – Markable: A Powerful Markdown Editor Plus Previewer With Bonus Features
- TextDown for Google Chrome – TextDown: Get a Markdown Editor Built Into Google Chrome
- Gingko: Online Editor – Gingko: An Online Word Processor That Could Change The Way You Write
- Markdown Here – Markdown Here: Use Markdown Text In Gmail & Have It Rendered [Chrome]
Composer is useful if you plan to plan to do a lot of writing in Markdown. It features “smart pairs” of characters, (e.g., parenthesis, quotation marks) that when typed the cursor gets inserted in the middle of the characters so you can immediately type content and keep your hands on the keys.
Composer also contains other useful automatic features for creating MultiMarkdown tables, embedding URL links, and automatically closing header syntax by appending with the proper number of “#” characters.
This guide covered the basics of Markdown for use in any supported application. As with any language, the more you use Markdown the easier it is to remember.
For additional information about Markdown, I recommend Markdown for Writers, by Gene Wilburn (a free download in the iTunes Book Store, and Markdown, by David Sparks and Eddie Smith (also an iBooks book.)
MakeUseOf.com will continue to review new applications and other resources that related Markdown, so check the site regularly.
Let us know what you think of this guide and if you found the tutorials a useful introduction to the subject.
Bold and Italics
_Italicize_ or *italicize*
1. Item (Hit Return key = automatic numbers or bullets)
>Angle bracket on the first line of the blockquote.
![Image Tag] (direct image URL link)
Heading | Heading |Heading
—- |—- |—-
Item | Item | Item
Item | Item | Item
Guide Published: March 2014