Overview

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world's most popular markup languages.

Using Markdown is different than using a WYSIWYG editor. In an application like Microsoft Word, you click buttons to format words and phrases, and the changes are visible immediately. Markdown isn't like that. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different.

Headings

To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three, use three number signs (e.g., ### My Heading).

Paragraphs

To create paragraphs, use a blank line to separate one or more lines of text.

Line Breaks

To create a line break or new line, end a line with two or more spaces, and then press return.

Emphasis

You can add emphasis by making text bold or italic.

Bold

To bold text, add two asterisks (**) or underscores (__) before and after a word or phrase.

Italic

To italicize text, add one asterisk (*) or underscore (_) before and after a word or phrase.

Bold and Italic

To emphasize text with bold and italics at the same time, add three asterisks (***) or underscores (___) before and after a word or phrase.

Blockquotes

To create a blockquote, add a > in front of a paragraph.

Nested Blockquotes

Blockquotes can be nested. Add a >> in front of the paragraph you want to nest.

Lists

You can organize items into ordered and unordered lists.

Ordered Lists

To create an ordered list, add line items with numbers followed by periods. The numbers don't have to be in numerical order, but the list should start with the number one.

Unordered Lists

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items.

Code

To denote a word or phrase as code, enclose it in backticks (`).

Code Blocks

To create code blocks, indent every line of the block by at least four spaces or one tab, or use triple backticks (```) before and after the code block.

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Horizontal Rules

To create a horizontal rule, use three or more asterisks (***), dashes (---), or underscores (___) on a line by themselves.

Links

To create a link, enclose the link text in brackets (e.g., [Duck Duck Go]) and then follow it immediately with the URL in parentheses (e.g., (https://duckduckgo.com)).

Adding Titles

You can optionally add a title for a link. This will appear as a tooltip when the user hovers over the link. To add a title, enclose it in quotation marks after the URL.

Images

To add an image, add an exclamation mark (!), followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title in quotation marks after the path or URL.

Markdown

HTML

Rendered Output


<img src="https://mdg.imgix.net/assets/images/san-juan-mountains.jpg" alt="The San Juan Mountains" title="San Juan Mountains">

Escaping Characters

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (\) in front of the character.

Characters You Can Escape

You can use a backslash to escape the following characters:

Tables

To add a table, use three or more hyphens (---) to create each column's header, and use pipes (|) to separate each column. You can optionally add pipes on either end of the table.

Alignment

You can align text in the columns to the left, right, or center by adding a colon (:) to the left, right, or on both sides of the hyphens within the header row.