Markdown
Markdown
com/
Published March 2014
share:
This manual is the intellectual property of MakeUseOf. It must only be published in its original form. Using parts or republishing altered parts of this guide is prohibited without permission from MakeUseOf.com
Think youve got what it takes to write a manual for MakeUseOf.com? Were always willing to hear a pitch! Send your ideas to justinpot@makeuseof.com.
LEARNING MARKDOWN
Table Of Contents
1.What is Markdown? What Is Markdown? Why Use Markdown? 2.How Markdown Works 3.Learn Markdown In 20 Minutes or Less StackEdit: Web Application Mou: Mac OS X MarkdownPad 2: Windows Lets Get Started Headers Bold and Italics Keyboard Shortcuts Ordered Lists Unordered Lists Blockquotes Email Address Link Inline URL Links Adding Inline Images Horizontal Line Hard Line Break 4.Exporting and Printing Markdown Documents 5.MultiMarkdown Tutorials Strikethrough Footnotes Tables 6.Using Keyboard Shortcuts and Menu Items 7.Automation and Shortcut Tools TextExpander and Keyboard Maestro Markdown Services Tools 8.Markdown Editors for Every Platform Markdown Editors HTTP://MAKEUSEOF.COM BAKARI CHAVANU, HTTP://BAKARICHAVANU.WORDPRESS.COM 5 5 5 7 8 8 9 9 10 10 10 11 11 12 12 13 13 13 14 15 16 17 17 17 18 20 22 22 22 24 24 3
share:
LEARNING MARKDOWN
iOS Editors Mac Editors Android Google Chrome and Online Editors Windows 9.Conclusion: Where To Go From Here Appendix: Cheat Sheet 24 25 25 25 25 26 27
4
share:
LEARNING MARKDOWN
1.What is Markdown?
Theres 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? Lets try to answer that together. Markdown was developed in 2004 by writer andbloggerJohn Gruber. DeveloperFletcher T. Penneylater created a subset of Markdown, called MultiMarkdown, which is also be explained in this guide.
What Is Markdown?
Markdown is essentially a syntax language for formatting text as you write. Its 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.
If youre 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 todays 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 Apples 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 Apples 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 youre 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.
5
share:
LEARNING 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.
6
share:
LEARNING MARKDOWN
7
share:
LEARNING MARKDOWN
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.
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.
8
share:
LEARNING MARKDOWN
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 toMarkdownPad Proto 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).
9
share:
LEARNING MARKDOWN
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. Youre 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.
Headers
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 doesnt 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.
Now lets 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. Type: Use underscore key to _italicize_ text. Type: 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. HTTP://MAKEUSEOF.COM BAKARI CHAVANU, HTTP://BAKARICHAVANU.WORDPRESS.COM 10
share:
LEARNING MARKDOWN
Keyboard Shortcuts
Note: You may have already noticed in the application youre 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
Type: 1. Apple
Ordered lists are pretty straightforward. If youre using a Markdown editor, it will recognize that youre 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.
11
share:
LEARNING MARKDOWN
Unordered Lists
Type: * Apple 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.
Blockquotes
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. Heres how it works: Copy and paste these two dummy paragraphs in the editor youre 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 theres a space between the two paragraphs. Next, type the greater than key, >, right before the word, Pudding, in order to blockquote that paragraph.
12
share:
LEARNING MARKDOWN
Note: The style of the blockquote may be slightly different from editor to editor.
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. <Joeblow@garage.com>
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 isshown. 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:
You can use Markdown to add inline images, but the link image must be posted and linked somewhere on the Internet, HTTP://MAKEUSEOF.COM BAKARI CHAVANU, HTTP://BAKARICHAVANU.WORDPRESS.COM 13
share:
LEARNING MARKDOWN
such asImageShack.us. Heres how to set it up. Copy and paste the following text and direct image link in the editor: This the MakeUseOf logo: (http://main.makeuseoflimited.netdna-cdn.com/wp-content/uploads/2006/07/muosquares.png) Type this reference tag in front of the image link. ![MUO logo] 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 Line
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.
14
share:
LEARNING MARKDOWN
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>
15
share:
LEARNING MARKDOWN
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.
16
share:
LEARNING MARKDOWN
5.MultiMarkdown Tutorials
Now we turn to tutorials for using MultiMarkdown, which is simply a subset of Markdown syntax. MultiMarkdown is a little more complex, but its especially useful for blogging and academic writing.
Strikethrough
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
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 drage tart sesame snaps. Cotton candy marzipan icing. Bear claw gingerbread lollipop. Unerdwear.com powder sesame snaps sesame snaps unerdwear.com drage 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, were 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. HTTP://MAKEUSEOF.COM BAKARI CHAVANU, HTTP://BAKARICHAVANU.WORDPRESS.COM 17
share:
LEARNING MARKDOWN
After you add the colon to the reference numbers, the footnotes will become linkable. A horizontal line will automatically appear above the footnoted references.
Tables
Markdown cant handle complex tables, but if you need to categorize content so its 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 doesnt 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.
18
share:
LEARNING MARKDOWN
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.
19
share:
LEARNING MARKDOWN
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.
20
share:
LEARNING MARKDOWN
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.
21
share:
LEARNING MARKDOWN
TextExpander(MUOreview 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. Its 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 Im not using a Markdown editor that includes the shortcut. Keyboard Maestro(MUOreview 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 atA 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.
Another way to apply Markdown is using the Services Menu feature in OS X (read more onapplying Markdown with the services menu). Developer Brett Terpstra has created a set ofAutomator workflows, saved as service tools, that apply Markdown syntax to a selected text in any application using the drop-down Services menu.
22
share:
LEARNING MARKDOWN
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 PDFMUO Guide to Mac Automationfor how use Automator.
23
share:
LEARNING MARKDOWN
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 dont 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 youre 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 Im 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.
Markdown Editors
iOS Editors
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 Youve Never Used Drafts -Drafts: The Ultimate Notes App For The iPhone and iPad [iOS]
24
share:
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.
Android
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
Windows
MarkdownPad -MarkdownPad: A Fully Featured Text To HTML Editor For Windows
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. HTTP://MAKEUSEOF.COM BAKARI CHAVANU, HTTP://BAKARICHAVANU.WORDPRESS.COM 25
share:
LEARNING MARKDOWN
26
share:
LEARNING MARKDOWN
Ordered List
2. Item 3. Item
Blockquotes Links
<URL Link> [Anchor] (URL)
Inline Image
----
[^1]:
Table
27
share:
Did you like this PDF Guide? Then why not visit MakeUseOf.com for daily posts on cool websites, free software and internet tips?
If you want more great guides like this, why not subscribe to MakeUseOf and receive instant access to 50+ PDF Guides like this one covering wide range of topics. Moreover, you will be able to download free Cheat Sheets, Free Giveaways and other cool things.
Follow MakeUseOf:
Think youve got what it takes to write a manual for MakeUseOf.com? Were always willing to hear a pitch! Send your ideas to justinpot@makeuseof.com.