Write faster: Your manual to Markdown, the web's simplest plain-text syntax

Writing only requires words, a bit of punctuation, and perhaps some paragraph breaks to organize thoughts. And yet—copy pasting content from one system into another almost always leads to wonky formatting.

Markdown fixes that, with simple formatting that looks the same everywhere. Here's how to use the world's most popular text formatting language—and some great apps to help.

Table of contents:

• What is Markdown?

• Markdown cheat sheet

• How to format text in Markdown

• Advanced Markdown: Lists, tables, and more

• The best Markdown writing apps

• What can you do with Markdown?

What is Markdown?

Imagine typing on a mechanical typewriter, with only letters and punctuation at your fingertips. There are no italics, no color options, no larger typeface for headers. How do you emphasize words, set apart quotes, and both make your document nicer looking and easier to read at the same time?

The simplest way would be to repurpose some special characters. Perhaps use a hashtag for headers, an underscore for italics, and an asterisk for strong, bold words.

With that, you'd have reinvented a basic version of Markdown.

Markdown was created in 2004 by John Gruber and Aaron Swartz as a way to format text for the web using simple characters including asterisks, underscores, and brackets. "The overriding design goal for Markdown's formatting syntax is to make it as readable as possible," writes Gruber on Markdown's main page. Format your text with a few symbols, and it's still perfectly readable—both by humans and by programs which could turn the text into even more readable PDFs, websites, and printed books.

Formatting text with Markdown is far more precise than the rich text formatting Word offers, while far simpler to write—and read—than HTML code. Paste Markdown-formatted text into another app, and it always looks the exact same—something you couldn't say for formatted text copied from Word.

Markdown is the best of the plain and formatted worlds, an ideal way to write in a world where we each have our own favorite writing apps and blogging platforms.

It's the one simple type of coding everyone should learn to use. So let's get started.

Markdown cheat sheet

How to format text in Markdown

Ready to add some formatting to your text? Here are the basics:

• Italics: Add one asterisk or underscore around your text *like this* or _this_

• Bold: Add two asterisks or underscores around your text **like this** or __this__

• Bold and Italic: Add three asterisks or underscores around your text ***like this*** or ___this___

You can even mix it up. Want a whole sentence in italics, with one word in bold?

*This **should** work*.

Got that? Now, let's get a bit fancier.

Sentences and paragraphs don't need anything special. Just make sure to leave a blank line between each paragraph, and you'll be good. Then, to add fancier things to your document:

• Links: Add brackets around the linked text, then add a parenthesis, your link, and a close parenthesis, like this: [Zapier](https://zapier.com/)

• Image: Type an exclamation mark, then an open bracket, then add alt text to describe your image, then close the bracket and add a parenthesis, paste a link to your image, then close the parentheses, like this: ![Zapier Logo](logo.png)

• Quotes: Add a greater-than sign in front of each line of quoted text, like this: > Just do it!

• Code: Add four spaces before each line of code, or a backtick before and after the code, like this: `<a href="https://zapier.com/">Zapier</a>`

• Strikethrough: Add two tildes around the text ~~like this~~ (though this may not work in all Markdown apps)

With all that stuff, you might want to break your document into sections with Headings. Markdown uses standard HTML-style headings, but you add them with a hash or pound symbol. For the largest headings, or H1 in HTML, add one hash symbol and a space in front of a line of text—or add two hash symbols without a space between them for H2, 3 for H3, and so on, like this:

# Our important Story

A long time ago...

## The first section

Some more text...

Ok. Looks like you've got the basics down. Try writing your own story with a bit of Markdown formatting, and you should quickly get something like this—here's the before and after.

Let's add a bit more to that.

Advanced Markdown formatting

There are only two more things you'll likely want to add to your Markdown document: lists and tables.

Lists are simple. For unordered lists, just add a dash, asterisk, or plus symbol before each line in your list, like this:

- Something

- Another thing

- Yet one more thing

Ordered lists work the same, but with numbers and periods instead of dashes, like this:

1. First thing

2. Second thing

3. Third thing

Or you could mix them and add nested lists (in most Markdown apps, anyhow) just by adding two spaces before the nested items, like this:

1. First thing

- Something

- Another thing

2. Second thing

3. Third thing

Tables are the trickiest thing in Markdown, and they're also only supported in some Markdown apps. Essentially, to make a table, add a pipe character—this: |—before and after every cell in the table, and add a row of dashes to separate your header cell. To make everything look nicer, use tabs to separate text instead of spaces. Here's how it should look:

| Food | Price |

| ----- | ----- |

| Eggs | $2.99 |

| Bacon | $4.99 |

| Bread | $1.99 |

With a bit of tweaking, you should be able to get your lists and tables to look something like this:

And that's it. With those handful of characters and tricks, you'll be able to format anything you want with Markdown. Want to embed a GIF or video? Just upload the file to your site, then use the image embed. Want to embed a YouTube video, form, or any other web element? Just paste the embed code into your document, and it'll render just fine on most websites.

You're now ready to start writing in Markdown. Want a new app to help you out?

The 9 best Markdown writing apps

All Markdown requires is plain text. You could write Markdown-formatted text in Word, in any text editor, on a typewriter, or even etch it into sand with a stick.

Or you could go fancy with a writing app designed for Markdown text. Typically, Markdown writing apps are bare-bones, with all distractions taken away to help you focus on writing. They let you add formatting with keyboard shortcuts like Ctrl+B for bold, and will add the asterisks or other characters automatically. Then, when you're done writing, they include export options to copy your text as rich text, HTML, or perhaps save it as a PDF or formatted eBook.

Here are some of the best.

Or, you actually might not need a new app. You can use Markdown formatting in Google Docs or Word—or a simple text editor like Notepad or TextEdit, and it'll work just the same.

For the nice, typewriter-like feel most Markdown apps bring, use a monospaced typeface like Courier Prime, along an off-white background color and a gray color for your text. Then, remember to save the finished document in .txt format so you can open it anywhere without having to rely on Word or another word processor app.

What can you do with Markdown?

You've written something amazing, something you're ready to share with the world. You could just copy your Markdown-formatted text and share it or print it out, but it'd look a tiny bit odd to most people.

Instead, you should turn it into beautifully formatted documents, books, websites, presentations, and more. Here's how.

Print

Writing anything lengthy takes a number of steps. Once you've written your text, it'll need to be edited, formatted into a print book or brochure, tweaked to look great in a PDF or a mobile-ready eBook, then distributed to the world.

Rich text quickly becomes a problem, as your text formatting slowly changes from each different app in the publishing workflow. Markdown, instead, keeps your text consistent—and makes formatting as easy as writing some CSS.

All you'll need is a Markdown writing app and an export tool to turn Markdown into eBooks, PDFs, or anything else you want. Or you might just need the writing tool: iA Writer and Byword include simple formatting to export text as a PDF or a print document, while Ulysses and Scrivener include customizable export templates to publish Markdown as eBooks and more.

If you want a tool just for turning Markdown into beautiful documents, Pandoc is one of the most powerful Markdown export tools. It can be tricky to master, though, and only runs in Terminal or your command prompt. For a simpler way to export Markdown, Marked is a great option with customizable PDF and eBook templates. Or, you can use Zapier's Formatter tool to convert Markdown text to HTML, then send it to any of your apps for safekeeping or publication.

If you're writing a book, just upload your Markdown files to LeanPub, and it'll turn them into print-ready PDFs and Kindle and iBooks-ready eBooks, and even let you sell your book right on its site.

Publish

Blogging is where Markdown shines brightest. It started out with a plugin for Movable Type and since has spread to almost every new blogging platform.

Tumblr was one of the first blog platforms to support Markdown. Just click the gear icon when writing a post, and select Markdown under the Text Editor options to use Markdown to format your posts. In Squarespace, just use the Markdown block when adding text to your site—and you can set it as your default text block if you'd like.

The blogging platform Ghost is designed around Markdown; write your post with Markdown formatting as you please. Flat-file CMS apps like Kirby and Jekyll are also designed around Markdown-formatted text files.

WordPress supports Markdown, too. It's built into WordPress.com—just use the Markdown block on your post or page. On a self-hosted WordPress site, you can add Markdown support with the Jetpack plugin.

Medium's known for having an easy-to-use editor, though it doesn't support Markdown right now. Instead, though, you can use some of the most popular Markdown apps—including Byword and iA Writer—to publish Markdown-formatted text directly on Medium.

Present

PowerPoint is overkill for most presentations. If your presentation is just text and images, you could just write your notes in Markdown and turn them directly into a presentation.

Deckset is one of the most popular Markdown presentation apps. Drag a Markdown text file into the app, then pick from a few templates, and you'll have a presentation in seconds. Texts, one of the writing apps mentioned above, lets you export your documents as presentations, too.

Alternatively, you can turn Markdown into a web-ready presentation using toolkits like Remark.js and Cleaver. Your new presentation could be shown from a browser—perhaps using a Chromecast—or you could just upload it to your website as a quick way to publish a presentation.

The benefits of Markdown formatting

When every word matters, it's words that should have the full focus—not formatting. Markdown quickly adds the most basic formatting to your text and lets you trust that the finished work will look exactly like you intended.

It might take time to become fluent at Markdown. But it's a worthwhile investment for simpler, more consistent writing for the web.

Related reading:

• The best free writing software

• How I wrote my novel in a note-taking app

• Write better: The 10 most common writing mistakes you should avoid

This article was originally published in January 2016. The most recent update, with contributions from Melissa King, was in February 2025.