Markdown Guide

Overview
This Markdown cheat sheet provides a quick overview of all the Markdown syntax elements. It can’t cover every
edge case, so if you need more information about any of these elements, refer to the reference guides for basic
syntax and extended syntax.
Basic Syntax
These are the elements outlined in John Gruber’s original design document. All Markdown applications support
these elements.
Element Markdown Syntax
Heading # H1
## H2
### H3
Bold **bold text**
Italic *italicized text*
Blockquote > blockquote
Ordered List 1. First item

2. Second item
3. Third item
Unordered List - First item

- Second item
- Third item
Code `code`
Horizontal Rule ---
Link [title](https://www.example.com)
Image ![alt text](image.jpg)
Extended Syntax
These elements extend the basic syntax by adding additional features. Not all Markdown applications support
these elements.
Element Markdown Syntax
Table | Syntax | Description |

| ----------- | ----------- |
| Header | Title |
| Paragraph | Text |
Fenced Code Block ```

{
"firstName": "John",
"lastName": "Smith",
"age": 25
}
```
Footnote Here's a sentence with a footnote. [^1]
[^1]: This is the footnote.
Heading ID ### My Great Heading {#custom-id}
Definition List term

: definition
Strikethrough ~~The world is flat.~~
Task List - [x] Write the press release

- [ ] Update the website
- [ ] Contact the media
Emoji That is so funny! :joy:

(see also Copying and Pasting Emoji)
Highlight I need to highlight these ==very important words==.
Subscript H~2~O
Superscript X^2^
What is Markdown? What is Markdown?
Why Use Markdown?

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text
Kicking the Tires
documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup
languages. How Does it Work?
What’s Markdown Good For?

Using Markdown is different than using a WYSIWYG editor. In an application like Microsoft Word, you click buttons
Flavors of Markdown
to format words and phrases, and the changes are visible immediately. Markdown isn’t like that. When you create
Additional Resources
a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look
different.
For example, to denote a heading, you add a number sign before it (e.g., # Heading One). Or to make a phrase
bold, you add two asterisks before and after it (e.g., **this text is bold**). It may take a while to get used to
seeing Markdown syntax in your text, especially if you’re accustomed to WYSIWYG applications. The screenshot
below shows a Markdown file displayed in the Visual Studio Code text editor.
You can add Markdown formatting elements to a plaintext file using a text editor application. Or you can use one
of the many Markdown applications for macOS, Windows, Linux, iOS, and Android operating systems. There are
also several web-based applications specifically designed for writing in Markdown.
Depending on the application you use, you may not be able to preview the formatted document in real time. But
that’s okay. According to Gruber, Markdown syntax is designed to be readable and unobtrusive, so the text in
Markdown files can be read even if it isn’t rendered.
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea
is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s
been marked up with tags or formatting instructions.
Why Use Markdown?

You might be wondering why people use Markdown instead of a WYSIWYG editor. Why write with Markdown when
you can press buttons in an interface to format your text? As it turns out, there are several reasons why people
use Markdown instead of WYSIWYG editors.
Markdown can be used for everything. People use it to create websites, documents, notes, books,
presentations, email messages, and technical documentation.
Markdown is portable. Files containing Markdown-formatted text can be opened using virtually any
application. If you decide you don’t like the Markdown application you’re currently using, you can import
your Markdown files into another Markdown application. That’s in stark contrast to word processing
applications like Microsoft Word that lock your content into a proprietary file format.
Markdown is platform independent. You can create Markdown-formatted text on any device running any
operating system.
Markdown is future proof. Even if the application you’re using stops working at some point in the future,
you’ll still be able to read your Markdown-formatted text using a text editing application. This is an important
consideration when it comes to books, university theses, and other milestone documents that need to be
preserved indefinitely.
Markdown is everywhere. Websites like Reddit and GitHub support Markdown, and lots of desktop and web-
based applications support it.
Kicking the Tires

The best way to get started with Markdown is to use it. That’s easier than ever before thanks to a variety of free
tools.
You don’t even need to download anything. There are several online Markdown editors that you can use to try
writing in Markdown. Dillinger is one of the best online Markdown editors. Just open the site and start typing in
the left pane. A preview of the rendered document appears in the right pane.
You’ll probably want to keep the Dillinger website open as you read through this guide. That way you can try the
syntax as you learn about it. After you’ve become familiar with Markdown, you may want to use a Markdown
application that can be installed on your desktop computer or mobile device.
How Does it Work?

Dillinger makes writing in Markdown easy because it hides the stuff happening behind the scenes, but it’s worth
exploring how the process works in general.
When you write in Markdown, the text is stored in a plaintext file that has an .md or .markdown extension. But then
what? How is your Markdown-formatted file converted into HTML or a print-ready document?
The short answer is that you need a Markdown application capable of processing the Markdown file. There are
lots of applications available — everything from simple scripts to desktop applications that look like Microsoft
Word. Despite their visual differences, all of the applications do the same thing. Like Dillinger, they all convert
Markdown-formatted text to HTML so it can be displayed in web browsers.
Markdown applications use something called a Markdown processor (also commonly referred to as a “parser” or
an “implementation”) to take the Markdown-formatted text and output it to HTML format. At that point, your
document can be viewed in a web browser or combined with a style sheet and printed. You can see a visual
representation of this process below.
Note: The Markdown application and processor are two separate components. For the sake of brevity, I've
combined them into one element ("Markdown app") in the figure below.
To summarize, this is a four-part process:
1. Create a Markdown file using a text editor or a dedicated Markdown application. The file should have an .md
or .markdown extension.
2. Open the Markdown file in a Markdown application.
3. Use the Markdown application to convert the Markdown file to an HTML document.
4. View the HTML file in a web browser or use the Markdown application to convert it to another file format, like
PDF.
From your perspective, the process will vary somewhat depending on the application you use. For example,
Dillinger essentially combines steps 1-3 into a single, seamless interface — all you have to do is type in the left
pane and the rendered output magically appears in the right pane. But if you use other tools, like a text editor with
a static website generator, you’ll find that the process is much more visible.
What’s Markdown Good For?

Markdown is a fast and easy way to take notes, create content for a website, and produce print-ready documents.
It doesn’t take long to learn the Markdown syntax, and once you know how to use it, you can write using
Markdown just about everywhere. Most people use Markdown to create content for the web, but Markdown is
good for formatting everything from email messages to grocery lists.
Here are some examples of what you can do with Markdown.
Websites
Markdown was designed for the web, so it should come as no surprise that there are plenty of applications
specifically designed for creating website content.
If you’re looking for the simplest possible way to create a website with Markdown files, check out blot.im. After
you sign up for Blot, it creates a Dropbox folder on your computer. Just drag and drop your Markdown files into
the folder and — poof! — they’re on your website. It couldn’t be easier.
If you’re familiar with HTML, CSS, and version control, check out Jekyll, a popular static site generator that takes
Markdown files and builds an HTML website. One advantage to this approach is that GitHub Pages provides free
hosting for Jekyll-generated websites. If Jekyll isn’t your cup of tea, just pick one of the many other static site
generators available.
Note: I used Jekyll to create the Markdown Guide. You can view the source code on GitHub.
If you’d like to use a content management system (CMS) to power your website, take a look at Ghost. It’s a free
and open-source blogging platform with a nice Markdown editor. If you’re a WordPress user, you’ll be happy to
know there’s Markdown support for websites hosted on WordPress.com. Self-hosted WordPress sites can use the
Jetpack plugin.
Documents
Markdown doesn’t have all the bells and whistles of word processors like Microsoft Word, but it’s good enough for
creating basic documents like assignments and letters. You can use a Markdown document authoring application
to create and export Markdown-formatted documents to PDF or HTML file format. The PDF part is key, because
once you have a PDF document, you can do anything with it — print it, email it, or upload it to a website.
Here are some Markdown document authoring applications I recommend:
Mac: MacDown, iA Writer, or Marked 2

iOS / Android: iA Writer
Windows: ghostwriter or Markdown Monster
Linux: ReText or ghostwriter
Web: Dillinger or StackEdit
Tip: iA Writer provides templates for previewing, printing, and exporting Markdown-formatted documents.
For example, the "Academic – MLA Style" template indents paragraphs and adds double sentence spacing.
Notes
In nearly every way, Markdown is the ideal syntax for taking notes. Sadly, Evernote and OneNote, two of the most
popular note applications, don’t currently support Markdown. The good news is that several other note
applications do support Markdown:
Obsidian is a popular Markdown note-taking application loaded with features.

Simplenote is a free, barebones note-taking application available for every platform.
Notable is a note-taking application that runs on a variety of platforms.
Bear is an Evernote-like application available for Mac and iOS devices. It doesn’t exclusively use Markdown
by default, but you can enable Markdown compatibility mode.
Joplin is a note taking application that respects your privacy. It’s available for every platform.
Boostnote bills itself as an “open source note-taking app designed for programmers.”
If you can’t part with Evernote, check out Marxico, a subscription-based Markdown editor for Evernote, or use
Markdown Here with the Evernote website.
Books
Looking to self-publish a novel? Try Leanpub, a service that takes your Markdown-formatted files and turns them
into an electronic book. Leanpub outputs your book in PDF, EPUB, and MOBI file format. If you’d like to create
paperback copies of your book, you can upload the PDF file to another service such as Kindle Direct Publishing.
To learn more about writing and self-publishing a book using Markdown, read this blog post.
Presentations
Believe it or not, you can generate presentations from Markdown-formatted files. Creating presentations in
Markdown takes a little getting used to, but once you get the hang of it, it’s a lot faster and easier than using an
application like PowerPoint or Keynote. Remark (GitHub project) is a popular browser-based Markdown slideshow
tool, as are Cleaver (GitHub project) and Marp (GitHub project). If you use a Mac and would prefer to use an
application, check out Deckset or Hyperdeck.
Email
If you send a lot of email and you’re tired of the formatting controls available on most email provider websites,
you’ll be happy to learn there’s an easy way to write email messages using Markdown. Markdown Here is a free
and open-source browser extension that converts Markdown-formatted text into HTML that’s ready to send.
Collaboration
Collaboration and team messaging applications are a popular way of communicating with coworkers and friends
at work and home. These applications don’t utilize all of Markdown’s features, but the features they do provide are
fairly useful. For example, the ability to bold and italicize text without using the WYSIWYG interface is pretty
handy. Slack, Discord, Wiki.js, and Mattermost are all good collaboration applications.
Documentation
Markdown is a natural fit for technical documentation. Companies like GitHub are increasingly switching to
Markdown for their documentation — check out their blog post about how they migrated their Markdown-
formatted documentation to Jekyll. If you write documentation for a product or service, take a look at these handy
tools:
Read the Docs can generate a documentation website from your open source Markdown files. Just connect
your GitHub repository to their service and push — Read the Docs does the rest. They also have a service
for commercial entities.
MkDocs is a fast and simple static site generator that’s geared towards building project documentation.
Documentation source files are written in Markdown and configured with a single YAML configuration file.
MkDocs has several built in themes, including a port of the Read the Docs documentation theme for use
with MkDocs. One of the newest themes is MkDocs Material.
Docusaurus is a static site generator designed exclusively for creating documentation websites. It supports
translations, search, and versioning.
VuePress is a static site generator powered by Vue and optimized for writing technical documentation.
Jekyll was mentioned earlier in the section on websites, but it’s also a good option for generating a
documentation website from Markdown files. If you go this route, be sure to check out the Jekyll
documentation theme.
Flavors of Markdown
One of the most confusing aspects of using Markdown is that practically every Markdown application implements
a slightly different version of Markdown. These variants of Markdown are commonly referred to as flavors. It’s your
job to master whatever flavor of Markdown your application has implemented.
To wrap your head around the concept of Markdown flavors, it might help to think of them as language dialects.
People in New York City speak English just like the people in London, but there are substantial differences
between the dialects used in both cities. The same is true for people using different Markdown applications. Using
Dillinger to write with Markdown is a vastly different experience than using Ulysses.
Practically speaking, this means you never know exactly what a company means when they say they support
“Markdown.” Are they talking about only the basic syntax elements, or all of the basic and extended syntax
elements combined, or some arbitrary combination of syntax elements? You won’t know until you read the
documentation or start using the application.
If you’re just starting out, the best advice I can give you is to pick a Markdown application with good Markdown
support. That’ll go a long way towards maintaining the portability of your Markdown files. You might want to store
and use your Markdown files in other applications, and to do that you need to start with an application that
provides good support. You can use the tool directory to find an application that fits the bill.
Additional Resources
There are lots of resources you can use to learn Markdown. Here are some other introductory resources:
John Gruber’s Markdown documentation. The original guide written by the creator of Markdown.
Markdown Tutorial. An open source website that allows you to try Markdown in your web browser.
Awesome Markdown. A list of Markdown tools and learning resources.
Typesetting Markdown. A multi-part series that describes an ecosystem for typesetting Markdown
documents using pandoc and ConTeXt.
Overview Overview
Headings
Nearly all Markdown applications support the basic syntax outlined in the original Markdown design document.
Paragraphs
There are minor variations and discrepancies between Markdown processors — those are noted inline wherever
possible. Line Breaks
Emphasis
Blockquotes
Headings Lists
To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use Code
should correspond to the heading level. For example, to create a heading level three (<h3>), use three number Horizontal Rules
signs (e.g., ### My Header). Links
Images
Markdown HTML Rendered Output Escaping Characters
HTML
# Heading level 1 <h1>Heading level 1</h1>
Heading level 1
## Heading level 2 <h2>Heading level 2</h2>
Heading level 2
### Heading level 3 <h3>Heading level 3</h3>
Heading level 3
#### Heading level 4 <h4>Heading level 4</h4>

Heading level 4
##### Heading level 5 <h5>Heading level 5</h5>

Heading level 5
###### Heading level 6 <h6>Heading level 6</h6>

Heading level 6
Alternate Syntax
Alternatively, on the line below the text, add any number of == characters for heading level 1 or -- characters for
heading level 2.
Markdown HTML Rendered Output
Heading level 1 <h1>Heading level 1</h1>

===============
Heading level 1
Heading level 2 <h2>Heading level 2</h2>
---------------
Heading level 2
Heading Best Practices

Markdown applications don’t agree on how to handle a missing space between the number signs (#) and the
heading name. For compatibility, always put a space between the number signs and the heading name.
Do this Don't do this
# Here's a Heading #Here's a Heading
You should also put blank lines before and after a heading for compatibility.
Try to put a blank line before... Without blank lines, this might not look right.
# Heading
# Heading Don't do this!
...and after a heading.
Paragraphs
To create paragraphs, use a blank line to separate one or more lines of text.
I really like using Markdown. <p>I really like using Markdown. I really like using Markdown.
</p>
I think I'll use it to format all
I think I'll use it to format
of my documents from now
all of my documents from now <p>I think I'll use it to format
on.
on. all of my documents from now on.
</p>
Paragraph Best Practices

Unless the paragraph is in a list, don’t indent paragraphs with spaces or tabs.
Note: If you need to indent paragraphs in the output, see the section on how to indent (tab).
Don't put tabs or spaces in front of your This can result in unexpected formatting
paragraphs. problems.
Keep lines left-aligned like this. Don't add tabs or spaces in front of
paragraphs.
Line Breaks
To create a line break or new line (<br>), end a line with two or more spaces, and then type return.
This is the first line. <p>This is the first line.<br> This is the first line.
And this is the second line. And this is the second line.</p> And this is the second line.
Line Break Best Practices

You can use two or more spaces (commonly referred to as “trailing whitespace”) for line breaks in nearly every
Markdown application, but it’s controversial. It’s hard to see trailing whitespace in an editor, and many people
accidentally or intentionally put two spaces after every sentence. For this reason, you may want to use something
other than trailing whitespace for line breaks. If your Markdown application supports HTML, you can use the <br>
HTML tag.
For compatibility, use trailing white space or the <br> HTML tag at the end of the line.
There are two other options I don’t recommend using. CommonMark and a few other lightweight markup
languages let you type a backslash (\) at the end of the line, but not all Markdown applications support this, so it
isn’t a great option from a compatibility perspective. And at least a couple lightweight markup languages don’t
require anything at the end of the line — just type return and they’ll create a line break.
First line with two spaces after. First line with a backslash after.\
And the next line. And the next line.
First line with the HTML tag after.<br> First line with nothing after.
And the next line. And the next line.
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. To bold the middle of a word for
emphasis, add two asterisks without spaces around the letters.
I just love **bold text**. I just love <strong>bold text</strong>. I just love bold text.
I just love __bold text__. I just love <strong>bold text</strong>. I just love bold text.
Love**is**bold Love<strong>is</strong>bold Loveisbold
Bold Best Practices

Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use
asterisks to bold the middle of a word for emphasis.
Love**is**bold Love__is__bold
Italic
To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word
for emphasis, add one asterisk without spaces around the letters.
Italicized text is the *cat's Italicized text is the <em>cat's Italicized text is the cat’s
meow*. meow</em>. meow.
Italicized text is the _cat's Italicized text is the <em>cat's Italicized text is the cat’s
meow_. meow</em>. meow.
A*cat*meow A<em>cat</em>meow Acatmeow
Italic Best Practices

asterisks to italicize the middle of a word for emphasis.
A*cat*meow A_cat_meow
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. To bold and italicize the middle of a word for emphasis, add three asterisks without spaces
around the letters.
This text is ***really This text is <em><strong>really This text is really

important***. important</strong></em>. important.
This text is ___really This text is <em><strong>really This text is really

important___. important</strong></em>. important.
This text is __*really This text is <em><strong>really This text is really

important*__. important</strong></em>. important.
This text is **_really This text is <em><strong>really This text is really

important_**. important</strong></em>. important.
This is This is really<em><strong>very</strong> This is

really***very***important </em>important text. reallyveryimportant
text. text.
Note: The order of the em and strong tags might be reversed depending on the Markdown processor you're
using.
Bold and Italic Best Practices

asterisks to bold and italicize the middle of a word for emphasis.
This is really***very***important text. This is really___very___important text.
Blockquotes
To create a blockquote, add a > in front of a paragraph.
> Dorothy followed her through many of the beautiful rooms in her castle.
The rendered output looks like this:
Dorothy followed her through many of the beautiful rooms in her castle.
Blockquotes with Multiple Paragraphs

Blockquotes can contain multiple paragraphs. Add a > on the blank lines between the paragraphs.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
Nested Blockquotes
Blockquotes can be nested. Add a >> in front of the paragraph you want to nest.
>
>> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
Blockquotes with Other Elements

Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you’ll need to
experiment to see which ones work.
> #### The quarterly results look great!

>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
> *Everything* is going according to **plan**.
The quarterly results look great!

Revenue was off the chart.
Profits were higher than ever.
Everything is going according to plan.
Blockquotes Best Practices

For compatibility, put blank lines before and after blockquotes.
Try to put a blank line before... Without blank lines, this might not look right.
> This is a blockquote
> This is a blockquote Don't do this!
...and after a blockquote.
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.
1. First item <ol> 1. First item

2. Second item <li>First item</li> 2. Second item
3. Third item <li>Second item</li> 3. Third item
4. Fourth item <li>Third item</li> 4. Fourth item
<li>Fourth item</li>
</ol>

</ol>

</ol>

1. Indented item <li>Third item 1. Indented item
2. Indented item <ol> 2. Indented item
4. Fourth item <li>Indented item</li> 4. Fourth item
<li>Indented item</li>
</ol>
</li>
</ol>
Ordered List Best Practices

CommonMark and a few other lightweight markup languages let you use a parenthesis ()) as a delimiter (e.g., 1)
First item), but not all Markdown applications support this, so it isn’t a great option from a compatibility
perspective. For compatibility, use periods only.
1. First item 1) First item

2. Second item 2) Second item
Unordered Lists
To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or
more items to create a nested list.
- First item <ul> First item

- Second item <li>First item</li> Second item
- Third item <li>Second item</li> Third item
- Fourth item <li>Third item</li> Fourth item
</ul>
* First item <ul> First item

* Second item <li>First item</li> Second item
* Third item <li>Second item</li> Third item
* Fourth item <li>Third item</li> Fourth item
</ul>
+ First item <ul> First item

+ Second item <li>First item</li> Second item
+ Third item <li>Second item</li> Third item
+ Fourth item <li>Third item</li> Fourth item
</ul>
- First item <ul> First item

- Second item <li>First item</li> Second item
- Third item <li>Second item</li> Third item
- Indented item <li>Third item Indented item
- Indented item <ul> Indented item
- Fourth item <li>Indented item</li> Fourth item
<li>Indented item</li>
</ul>
</li>
</ul>
Starting Unordered List Items With Numbers

If you need to start an unordered list item with a number followed by a period, you can use a backslash (\) to
escape the period.
- 1968\. A great year! <ul> 1968. A great year!

- I think 1969 was second <li>1968. A great year!</li> I think 1969 was second
best. <li>I think 1969 was second best. best.
</li>
</ul>
Unordered List Best Practices

Markdown applications don’t agree on how to handle different delimiters in the same list. For compatibility, don’t
mix and match delimiters in the same list — pick one and stick with it.
- First item + First item

- Second item * Second item
- Third item - Third item
- Fourth item + Fourth item
Adding Elements in Lists

To add another element in a list while preserving the continuity of the list, indent the element four spaces or one
tab, as shown in the following examples.
Tip: If things don't appear the way you expect, double check that you've indented the elements in the list
four spaces or one tab.
Paragraphs
* This is the first list item.

* Here's the second list item.
I need to add another paragraph below the second list item.
* And here's the third list item.
This is the first list item.

Here’s the second list item.
I need to add another paragraph below the second list item.
And here’s the third list item.
Blockquotes
* This is the first list item.

* Here's the second list item.
> A blockquote would look great below the second list item.
* And here's the third list item.
This is the first list item.

Here’s the second list item.
A blockquote would look great below the second list item.
And here’s the third list item.
Code Blocks
Code blocks are normally indented four spaces or one tab. When they’re in a list, indent them eight spaces or two
tabs.
1. Open the file.

2. Find the following code block on line 21:
<html>
<head>
<title>Test</title>
</head>
3. Update the title to match the name of your website.
1. Open the file.

2. Find the following code block on line 21:
<html>
<head>
<title>Test</title>
</head>
3. Update the title to match the name of your website.
Images
1. Open the file containing the Linux mascot.

2. Marvel at its beauty.
![Tux, the Linux mascot](/assets/images/tux.png)
3. Close the file.
1. Open the file containing the Linux mascot.

2. Marvel at its beauty.
3. Close the file.
Lists
You can nest an unordered list in an ordered list, or vice versa.
1. First item
2. Second item
3. Third item
- Indented item
- Indented item
4. Fourth item
1. First item
2. Second item
3. Third item
Indented item
Indented item
4. Fourth item
Code
To denote a word or phrase as code, enclose it in backticks (`).
At the command prompt, type At the command prompt, type At the command prompt,
`nano`. <code>nano</code>. type nano.
Escaping Backticks
If the word or phrase you want to denote as code includes one or more backticks, you can escape it by enclosing
the word or phrase in double backticks (``).
``Use `code` in your <code>Use `code` in your Markdown Use `code` in your
Markdown file.`` file.</code> Markdown file.
<html>
<head>
</head>
</html>
Note: To create code blocks without indenting lines, use fenced code blocks.
Horizontal Rules
To create a horizontal rule, use three or more asterisks (***), dashes (---), or underscores (___) on a line by
themselves.
***
---
_________________
The rendered output of all three looks identical:
Horizontal Rule Best Practices

For compatibility, put blank lines before and after horizontal rules.
Try to put a blank line before... Without blank lines, this would be a heading.
---
--- Don't do this!
...and after a horizontal rule.
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)).
My favorite search engine is [Duck Duck Go](https://duckduckgo.com).
My favorite search engine is Duck Duck Go.
Note: To link to an element on the same page, see linking to heading IDs. To create a link that opens in a
new tab or window, see the section on link targets.
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.
My favorite search engine is [Duck Duck Go](https://duckduckgo.com "The best search engine for privacy").
My favorite search engine is Duck Duck Go.
URLs and Email Addresses

To quickly turn a URL or email address into a link, enclose it in angle brackets.
<https://www.markdownguide.org>
<fake@example.com>
https://www.markdownguide.org
fake@example.com
Formatting Links
To emphasize links, add asterisks before and after the brackets and parentheses. To denote links as code, add
backticks in the brackets.
I love supporting the **[EFF](https://eff.org)**.

This is the *[Markdown Guide](https://www.markdownguide.org)*.
See the section on [`code`](#code).
I love supporting the EFF.

This is the Markdown Guide.
See the section on code.
Reference-style Links
Reference-style links are a special kind of link that make URLs easier to display and read in Markdown. Reference-
style links are constructed in two parts: the part you keep inline with your text and the part you store somewhere
else in the file to keep the text easy to read.
Formatting the First Part of the Link

The first part of a reference-style link is formatted with two sets of brackets. The first set of brackets surrounds
the text that should appear linked. The second set of brackets displays a label used to point to the link you’re
storing elsewhere in your document.
Although not required, you can include a space between the first and second set of brackets. The label in the
second set of brackets is not case sensitive and can include letters, numbers, spaces, or punctuation.
This means the following example formats are roughly equivalent for the first part of the link:
[hobbit-hole][1]
[hobbit-hole] [1]
Formatting the Second Part of the Link

The second part of a reference-style link is formatted with the following attributes:
1. The label, in brackets, followed immediately by a colon and at least one space (e.g., [label]: ).
2. The URL for the link, which you can optionally enclose in angle brackets.
3. The optional title for the link, which you can enclose in double quotes, single quotes, or parentheses.
This means the following example formats are all roughly equivalent for the second part of the link:
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle (Hobbit lifestyles)
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> "Hobbit lifestyles"
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Hobbit lifestyles'
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> (Hobbit lifestyles)
You can place this second part of the link anywhere in your Markdown document. Some people place them
immediately after the paragraph in which they appear while other people place them at the end of the document
(like endnotes or footnotes).
An Example Putting the Parts Together

Say you add a URL as a standard URL link to a paragraph and it looks like this in Markdown:
In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends
of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to
eat: it was a [hobbit-hole](https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Hobbit lifestyles"), and that means comfort.
Though it may point to interesting additional information, the URL as displayed really doesn’t add much to the
existing raw text other than making it harder to read. To fix that, you could format the URL like this instead:
In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends
of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to
eat: it was a [hobbit-hole][1], and that means comfort.
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> "Hobbit lifestyles"
In both instances above, the rendered output would be identical:
In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an
oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a hobbit-hole,
and that means comfort.
and the HTML for the link would be:
<a href="https://en.wikipedia.org/wiki/Hobbit#Lifestyle" title="Hobbit lifestyles">hobbit-hole</a>
Link Best Practices

Markdown applications don’t agree on how to handle spaces in the middle of a URL. For compatibility, try to URL
encode any spaces with %20. Alternatively, if your Markdown application supports HTML, you could use the a
HTML tag.
[link](https://www.example.com/my%20great%20page) [link](https://www.example.com/my great

page)
<a href="https://www.example.com/my great
page">link</a>
Parentheses in the middle of a URL can also be problematic. For compatibility, try to URL encode the opening
parenthesis (() with %28 and the closing parenthesis ()) with %29. Alternatively, if your Markdown application
supports HTML, you could use the a HTML tag.
[a novel](https://en.wikipedia.org/wiki/ [a novel](https://en.wikipedia.org/wiki/
The_Milagro_Beanfield_War_%28novel%29) The_Milagro_Beanfield_War_(novel))
<a href="https://en.wikipedia.org/wiki/
The_Milagro_Beanfield_War_(novel)">a novel</a>
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.
![The San Juan Mountains are beautiful!](/assets/images/san-juan-mountains.jpg "San Juan Mountains")
Note: To resize an image, see the section on image size. To add a caption, see the section on image
captions.
Linking Images
To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses.
[![An old rock in the desert](/assets/images/shiprock.jpg "Shiprock, New Mexico by Beau Rogers")](https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F
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.
\* Without the backslash, this would be a bullet in an unordered list.
* Without the backslash, this would be a bullet in an unordered list.
Characters You Can Escape

You can use a backslash to escape the following characters.
Character Name
\ backslash
` backtick (see also escaping backticks in code)
* asterisk
_ underscore
{} curly braces
[] brackets
<> angle brackets
() parentheses
# pound sign
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark
| pipe (see also escaping pipe in tables)
HTML
Many Markdown applications allow you to use HTML tags in Markdown-formatted text. This is helpful if you prefer
certain HTML tags to Markdown syntax. For example, some people find it easier to use HTML tags for images.
Using HTML is also helpful when you need to change the attributes of an element, like specifying the color of text
or changing the width of an image.
To use HTML, place the tags in the text of your Markdown-formatted file.
This **word** is bold. This <em>word</em> is italic.
This word is bold. This word is italic.
HTML Best Practices

For security reasons, not all Markdown applications support HTML in Markdown documents. When in doubt,
check your Markdown application’s documentation. Some applications support only a subset of HTML tags.
Use blank lines to separate block-level HTML elements like <div>, <table>, <pre>, and <p> from the surrounding
content. Try not to indent the tags with tabs or spaces — that can interfere with the formatting.
You can’t use Markdown syntax inside block-level HTML tags. For example, <p>italic and **bold**</p> won’t
work.
Overview Overview
Availability
The basic syntax outlined in the original Markdown design document added many of the elements needed on a
Tables
day-to-day basis, but it wasn’t enough for some people. That’s where extended syntax comes in.
Fenced Code Blocks
Several individuals and organizations took it upon themselves to extend the basic syntax by adding additional Footnotes
elements like tables, code blocks, syntax highlighting, URL auto-linking, and footnotes. These elements can be
Heading IDs
enabled by using a lightweight markup language that builds upon the basic Markdown syntax, or by adding an
Definition Lists
extension to a compatible Markdown processor.
Strikethrough
Task Lists
Availability Emoji
Highlight
Not all Markdown applications support extended syntax elements. You’ll need to check whether or not the
Subscript
lightweight markup language your application is using supports the extended syntax elements you want to use. If
it doesn’t, it may still be possible to enable extensions in your Markdown processor. Superscript
Automatic URL Linking
Disabling Automatic URL Linking

Lightweight Markup Languages
There are several lightweight markup languages that are supersets of Markdown. They include basic syntax and
build upon it by adding additional elements like tables, code blocks, syntax highlighting, URL auto-linking, and
footnotes. Many of the most popular Markdown applications use one of the following lightweight markup
languages:
CommonMark
GitHub Flavored Markdown (GFM)
Markdown Extra
MultiMarkdown
R Markdown
Markdown Processors
There are dozens of Markdown processors available. Many of them allow you to add extensions that enable
extended syntax elements. Check your processor’s documentation for more information.
Tables
To add a table, use three or more hyphens (---) to create each column’s header, and use pipes (|) to separate
each column. For compatibility, you should also add a pipe on either end of the row.
| Syntax | Description |
| ----------- | ----------- |
| Header | Title |
Syntax Description
Header Title
Paragraph Text
Cell widths can vary, as shown below. The rendered output will look the same.
| --- | ----------- |
| Header | Title |
Tip: Creating tables with hyphens and pipes can be tedious. To speed up the process, try using the
Markdown Tables Generator or AnyWayData Markdown Export. Build a table using the graphical interface,
and then copy the generated Markdown-formatted text into your file.
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 side
of the hyphens within the header row.
| Syntax | Description | Test Text |

| :--- | :----: | ---: |
| Header | Title | Here's this |
| Paragraph | Text | And more |
Syntax Description Test Text
Header Title Here’s this
Paragraph Text And more
Formatting Text in Tables

You can format the text within tables. For example, you can add links, code (words or phrases in backticks (`)
only, not code blocks), and emphasis.
You can’t use headings, blockquotes, lists, horizontal rules, images, or most HTML tags.
Tip: You can use HTML to create line breaks and add lists within table cells.
Escaping Pipe Characters in Tables

You can display a pipe (|) character in a table by using its HTML character code (|).
Fenced Code Blocks

The basic Markdown syntax allows you to create code blocks by indenting lines by four spaces or one tab. If you
find that inconvenient, try using fenced code blocks. Depending on your Markdown processor or editor, you’ll use
three backticks (```) or three tildes (~~~) on the lines before and after the code block. The best part? You don’t
have to indent any lines!
```
{
"age": 25
}
```
{
"age": 25
}
Tip: Need to display backticks inside a code block? See this section to learn how to escape them.
Syntax Highlighting
Many Markdown processors support syntax highlighting for fenced code blocks. This feature allows you to add
color highlighting for whatever language your code was written in. To add syntax highlighting, specify a language
next to the backticks before the fenced code block.
```json
{
"age": 25
}
```
{
"age": 25
}
Footnotes
Footnotes allow you to add notes and references without cluttering the body of the document. When you create a
footnote, a superscript number with a link appears where you added the footnote reference. Readers can click the
link to jump to the content of the footnote at the bottom of the page.
To create a footnote reference, add a caret and an identifier inside brackets ([^1]). Identifiers can be numbers or
words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote
itself — in the output, footnotes are numbered sequentially.
Add the footnote using another caret and number inside brackets with a colon and text ([^1]: My footnote.).
You don’t have to put footnotes at the end of the document. You can put them anywhere except inside other
elements like lists, block quotes, and tables.
Here's a simple footnote,[^1] and here's a longer one.[^bignote]
[^1]: This is the first footnote.
[^bignote]: Here's one with multiple paragraphs and code.
Indent paragraphs to include them in the footnote.
`{ my code }`
Add as many paragraphs as you like.
Here’s a simple footnote,1 and here’s a longer one.2
1. This is the first footnote. ↩
2. Here’s one with multiple paragraphs and code.
Indent paragraphs to include them in the footnote.
{ my code }
Add as many paragraphs as you like. ↩
Heading IDs
Many Markdown processors support custom IDs for headings — some Markdown processors automatically add
them. Adding custom IDs allows you to link directly to headings and modify them with CSS. To add a custom
heading ID, enclose the custom ID in curly braces on the same line as the heading.
### My Great Heading {#custom-id}
The HTML looks like this:
<h3 id="custom-id">My Great Heading</h3>
Linking to Heading IDs

You can link to headings with custom IDs in the file by creating a standard link with a number sign (#) followed by
the custom heading ID. These are commonly referred to as anchor links.
[Heading IDs](#heading-ids) <a href="#heading-ids">Heading IDs</a> Heading IDs
Other websites can link to the heading by adding the custom heading ID to the full URL of the webpage (e.g,
[Heading IDs](https://www.markdownguide.org/extended-syntax#heading-ids)).
Definition Lists
Some Markdown processors allow you to create definition lists of terms and their corresponding definitions. To
create a definition list, type the term on the first line. On the next line, type a colon followed by a space and the
definition.
First Term
: This is the definition of the first term.
Second Term
: This is one definition of the second term.
: This is another definition of the second term.
The HTML looks like this:
<dl>
<dt>First Term</dt>
<dd>This is the definition of the first term.</dd>
<dt>Second Term</dt>
<dd>This is one definition of the second term. </dd>
<dd>This is another definition of the second term.</dd>
</dl>
First Term
This is the definition of the first term.
Second Term
This is one definition of the second term.
This is another definition of the second term.
Strikethrough
You can strikethrough words by putting a horizontal line through the center of them. The result looks like this. This
feature allows you to indicate that certain words are a mistake not meant for inclusion in the document. To
strikethrough words, use two tilde symbols (~~) before and after the words.
~~The world is flat.~~ We now know that the world is round.
The world is flat. We now know that the world is round.
Task Lists
Task lists (also referred to as checklists and todo lists) allow you to create a list of items with checkboxes. In
Markdown applications that support task lists, checkboxes will be displayed next to the content. To create a task
list, add dashes (-) and brackets with a space ([ ]) in front of task list items. To select a checkbox, add an x in
between the brackets ([x]).
- [x] Write the press release

- [ ] Update the website
- [ ] Contact the media
Emoji
There are two ways to add emoji to Markdown files: copy and paste the emoji into your Markdown-formatted text,
or type emoji shortcodes.
Copying and Pasting Emoji

In most cases, you can simply copy an emoji from a source like Emojipedia and paste it into your document. Many
Markdown applications will automatically display the emoji in the Markdown-formatted text. The HTML and PDF
files you export from your Markdown application should display the emoji.
Tip: If you're using a static site generator, make sure you encode HTML pages as UTF-8.
Using Emoji Shortcodes

Some Markdown applications allow you to insert emoji by typing emoji shortcodes. These begin and end with a
colon and include the name of an emoji.
Gone camping! :tent: Be back soon.
That is so funny! :joy:
Gone camping! Be back soon.
That is so funny!
Note: You can use this list of emoji shortcodes, but keep in mind that emoji shortcodes vary from
application to application. Refer to your Markdown application's documentation for more information.
Highlight
This isn’t common, but some Markdown processors allow you to highlight text. The result looks like this . To
highlight words, use two equal signs (==) before and after the words.
I need to highlight these ==very important words==.
I need to highlight these very important words .
Alternatively, if your Markdown application supports HTML, you can use the mark HTML tag.
I need to highlight these <mark>very important words</mark>.
Subscript
This isn’t common, but some Markdown processors allow you to use subscript to position one or more characters
slightly below the normal line of type. To create a subscript, use one tilde symbol (~) before and after the
characters.
H~2~O
H2O
Tip: Be sure to test this in your Markdown application before using it. Some Markdown applications use one
tilde symbol before and after words not for subscript, but for strikethrough.
Alternatively, if your Markdown application supports HTML, you can use the sub HTML tag.
H<sub>2</sub>O
Superscript
This isn’t common, but some Markdown processors allow you to use superscript to position one or more
characters slightly above the normal line of type. To create a superscript, use one caret symbol (^) before and
after the characters.
X^2^
X2
Alternatively, if your Markdown application supports HTML, you can use the sup HTML tag.
X<sup>2</sup>
Automatic URL Linking

Many Markdown processors automatically turn URLs into links. That means if you type http://www.example.com,
your Markdown processor will automatically turn it into a link even though you haven’t used brackets.
http://www.example.com
Disabling Automatic URL Linking

If you don’t want a URL to be automatically linked, you can remove the link by denoting the URL as code with
backticks.
`http://www.example.com`
Overview Overview
Underline
The majority of people using Markdown will find that the basic and extended syntax elements cover their needs.
Indent (Tab)
But chances are that if you use Markdown long enough, you’ll inevitably discover that it doesn’t support
something you need. This page provides tips and tricks for working around Markdown’s limitations. Center
Color
Tip: These hacks aren't guaranteed to work in your Markdown application. If you need to use these hacks Comments
frequently, you should consider writing using something other than Markdown. Admonitions
Image Size
Image Captions
Underline Link Targets
Symbols
Underlined text is not something you typically see in web writing, probably because underlined text is nearly
Table Formatting
synonymous with links. However, if you’re writing a paper or a report, you may need the ability to underline words
and phrases. A couple of applications like Bear and Simplenote provide support for underlining text, but Table of Contents
Markdown doesn’t natively support underlining. If your Markdown processor supports HTML, you can use the Videos
<ins> HTML tag to underline text in your document.
Some of these words <ins>will be underlined</ins>.
Some of these words will be underlined.
Indent (Tab)
Tabs and whitespace have a special meaning in Markdown. You can use trailing whitespace to create line breaks,
and you can use tabs to create code blocks. But what if you need to indent a paragraph the old-fashioned way,
using the tab key? Markdown doesn’t provide an easy way of doing that.
Your best bet might be to use a Markdown editor that supports indentation. This is common in applications that
are more oriented towards desktop publishing. For example, iA Writer allows you to customize indentation settings
for the editor in the application preferences. It also provides template customization options so that you can make
the rendered document look the way you expect it to, indentation and all.
Another option, if your Markdown processor supports HTML, is to use the HTML entity for non-breaking space
( ). This should probably be your option of last resort as it can get awkward. Basically, every in your
Markdown source will be replaced with a space in the rendered output. So if you stick four instances of
before a paragraph, the paragraph will look like it’s indented four spaces.
This is the first sentence of my indented paragraph.
This is the first sentence of my indented paragraph.
Center
Having the ability to center text is a necessity when writing a paper or a report. Unfortunately, Markdown doesn’t
have any concept of text alignment (one possible exception is when using tables). The good news is that there’s
an HTML tag you can use: <center>. If your Markdown processor supports HTML, you can place these tags
around whatever text you want to center align.
<center>This text is centered.</center>
This text is centered.
The <center> HTML tag is technically supported but officially deprecated, which means it works for now but
you’re not supposed to be using it. Unfortunately, there’s not another pure HTML alternative. You could try using
one of the CSS alternatives. Not all Markdown applications provide CSS support, but if the one you’re using does,
here’s an alternative to the <center> tag:
<p style="text-align:center">Center this text</p>
If this is supported by your Markdown application, the output looks like this:
Center this text
Color
Markdown doesn’t allow you to change the color of text, but if your Markdown processor supports HTML, you can
use the <font> HTML tag. The color attribute allows you to specify the font color using a color’s name or the
hexadecimal #RRGGBB code.
<font color="red">This text is red!</font>
This text is red!
The <font> HTML tag is technically supported but officially deprecated, which means it works for now but you’re
not supposed to be using it. Unfortunately, there’s not another pure HTML alternative. You could try using one of
the CSS alternatives. Not all Markdown applications provide CSS support, but if the one you’re using does, here’s
an alternative to the <font> tag:
<p style="color:blue">Make this text blue.</p>
If this is supported by your Markdown application, the output looks like this:
Make this text blue.
Comments
Some people need the ability to write sentences in their Markdown files that will not appear in the rendered
output. These comments are essentially hidden text. The text is viewable by the author of the document, but it’s
not printed on the webpage or PDF. Markdown doesn’t natively support comments, but several enterprising
individuals have devised a solution.
To add a comment, place text inside brackets followed by a colon, a space, and a pound sign (e.g., [comment]:
#). You should put blank lines before and after a comment.
Here's a paragraph that will be visible.
[This is a comment that will be hidden.]: #
And here's another paragraph that's visible.
Here’s a paragraph that will be visible.
And here’s another paragraph that’s visible.
Tip: This tip comes from Stack Overflow. It's been peer-reviewed and used by thousands of people!
Admonitions
Admonitions are frequently used in documentation to call attention to warnings, notes, and tips. Markdown
doesn’t provide special syntax for admonitions, and most Markdown applications don’t provide support for
admonitions (one exception is MkDocs).
However, if you need to add admonitions, you might be able to use blockquotes with emoji and emphasis to create
something that looks similar to the admonitions you see on other websites.
> :warning: **Warning:** Do not push the big red button.
> :memo: **Note:** Sunrises are beautiful.
> :bulb: **Tip:** Remember to appreciate the little things in life.
Warning: Do not push the big red button.
Note: Sunrises are beautiful.
Tip: Remember to appreciate the little things in life.
Image Size
The Markdown syntax for images doesn’t allow you to specify the width and height of images. If you need to
resize an image and your Markdown processor supports HTML, you can use the img HTML tag with the width and
height attributes to set the dimensions of an image in pixels.
<img src="image.png" width="200" height="100">
The rendered output will contain the image resized to the dimensions you specified.
Image Captions
Markdown doesn’t natively support image captions, but there are two possible workarounds. If your Markdown
application supports HTML, you can use the figure and figcaption HTML tags to add a caption for your image.
<figure>
<img src="/assets/images/albuquerque.jpg"
alt="Albuquerque, New Mexico">
<figcaption>A single track trail outside of Albuquerque, New Mexico.</figcaption>
</figure>
A single track trail outside of Albuquerque, New Mexico.
Tip: If your Markdown application supports CSS, you can use CSS to style the appearance of the caption.
If your Markdown application doesn’t support HTML, you could try placing the caption directly below the image
and using emphasis.
![Albuquerque, New Mexico](/assets/images/albuquerque.jpg)

*A single track trail outside of Albuquerque, New Mexico.*
A single track trail outside of Albuquerque, New Mexico.
Link Targets
Some people like creating links that open in new tabs or windows. The Markdown syntax for links doesn’t allow
you to specify the target attribute, but if your Markdown processor supports HTML, you can use HTML to create
these links.
<a href="https://www.markdownguide.org" target="_blank">Learn Markdown!</a>
Learn Markdown!
Symbols
Markdown doesn’t provide special syntax for symbols. However, in most cases, you can copy and paste whatever
symbol you want to use into your Markdown document. For example, if you need to display Pi (π), just find the
symbol on a webpage and copy and paste it into your document. The symbol should appear as expected in the
rendered output.
Alternatively, if your Markdown application supports HTML, you can use the HTML entity for whatever symbol you
want to use. For example, if you want to display the copyright sign (©), you can copy and paste the HTML entity
for copyright (©) into your Markdown document.
Here’s a partial list of HTML entities for symbols:
Copyright (©) — ©

Registered trademark (®) — ®
Trademark (™) — ™
Euro (€) — €
Left arrow (←) — ←
Up arrow (↑) — ↑
Right arrow (→) — →
Down arrow (↓) — ↓
Degree (°) — °
Pi (π) — π
For a complete list of available HTML entities, refer to Wikipedia’s page on HTML entities.
Table Formatting
Markdown tables are notoriously finicky. You can’t use many Markdown syntax elements to format the text in table
cells. But there are workarounds for at least two common table issues: Line breaks and lists.
Line Breaks Within Table Cells

You can separate paragraphs within a table cell by using one or more <br> HTML tags.
| ----------- | ----------- |
| Header | Title |
| Paragraph | First paragraph. <br><br> Second paragraph. |
Syntax Description
Header Title
Paragraph First paragraph.
Second paragraph.
Lists Within Table Cells

You can add a list within a table cell by using HTML tags.
| ----------- | ----------- |
| Header | Title |
| List | Here's a list! <ul><li>Item one.</li><li>Item two.</li></ul> |
Syntax Description
Header Title
List Here's a list!

Item one.
Item two.
Table of Contents
Some Markdown applications like Markdeep can automatically generate a table of contents (also referred to as a
toc) from your headings, but this isn’t a feature provided by all Markdown applications. However, if your
Markdown application supports heading IDs, you can create a table of contents for your Markdown file using a list
and some links.
#### Table of Contents
- [Underline](#underline)
- [Indent](#indent)
- [Center](#center)
- [Color](#color)
Table of Contents
Underline
Indent
Center
Color
Videos
If your Markdown application supports HTML, you should be able to embed a video in your Markdown file by
copying and pasting the HTML code provided by a video website like YouTube or Vimeo. If your Markdown
application doesn’t support HTML, you can’t embed a video, but you can come close by adding an image and a
link to the video. You could do this with practically any video on any video service.
Since YouTube makes this easy, we’ll use them as an example. Take this video, for instance:
https://www.youtube.com/watch?v=8q2IjQOzVpE. The last part of the URL (8q2IjQOzVpE) is the ID of the video.
We can take that ID and put it in the following template:
[![Image alt text](https://img.youtube.com/vi/YOUTUBE-ID/0.jpg)](https://www.youtube.com/watch?v=YOUTUBE-ID)
YouTube automatically generates an image for every video (https://img.youtube.com/vi/YOUTUBE-ID/0.jpg),

so we can use that and link the image to the video on YouTube. After we replace the image alt text and add the ID
of the video, our example looks like this:
[![Less Than Jake — Scott Farcas Takes It On The Chin](https://img.youtube.com/vi/PYCxct2e0zI/0.jpg)](https://www.youtube.com/watch?v=PYCxct2e0zI)

Markdown Guide Get Started Cheat Sheet Basic Syntax Extended Syntax Hacks Tools Book Search
API
Programmatically access Markdown documentation.
Introduction Introduction
Basic Syntax Endpoint

The Markdown Guide API provides a subset of documentation from the Markdown Guide in JSON format. We
Cheat Sheet Endpoint
hope that software developers and organizations use this API to programmatically consume our documentation
and display it in applications and on websites. Changelog
Why?
Why create an API for Markdown documentation? Because there’s so much duplicated Markdown documentation
on the web! It seems like everybody has their own version of Markdown documentation for their application or
website. That’s a shame since most of it is exactly the same.
Then came the epiphany. We realized we could create a JSON API using documentation from the Markdown
Guide. That way, software developers could start using the API to include our documentation in their applications,
and organizations like universities and libraries could use the API to include our documentation on their websites.
We’d love to see the Markdown Guide become the central documentation repository for the thousands of
Markdown instructions sprinkled around the internet. Will it work? Who knows! One thing’s for sure though: We
can’t wait to see what you do with it.
Limitations
The Markdown Guide API is designed to provide only essential Markdown documentation. As a result, the API
doesn’t include all of the documentation available on the Markdown Guide website. For example, the Adding
Elements in Lists section is not available through the basic syntax endpoint.
Basic Syntax Endpoint

The basic syntax endpoint contains documentation about the Markdown elements outlined in John Gruber’s
design document and described on the Basic Syntax page.
API Endpoint
/api/v1/basic-syntax.json
Request
curl https://www.markdownguide.org/api/v1/basic-syntax.json
Response
1 {
2 "status": "OK",
3 "last_updated": "2017-11-04",
4 "basic_syntax": [
5 {
6 "name" : "Blockquotes",
7 "description" : "To create a blockquote, add a `>` in front of a paragraph.",
8 "examples" : [
9
10 {
11 "markdown" : "> Dorothy followed her through many of the beautiful rooms in her castle.",
12 "html" : "<blockquote><p>Dorothy followed her through many of the beautiful rooms in her castle.</p></blockquote>"
13 }
14
15 ],
16 "additional_examples" : [
17
18 {
19 "name" : "Blockquotes with Multiple Paragraphs",
20 "description" : "Blockquotes can contain multiple paragraphs. Add a `>` on the blank lines between the paragraphs.",
21 "markdown" : "> Dorothy followed her through many of the beautiful rooms in her castle.\n>\n> The Witch bade her clean the pots and kettles and sweep the floor and keep the fir
22 "html" : "<blockquote><p>Dorothy followed her through many of the beautiful rooms in her castle.</p><p>The Witch bade her clean the pots and kettles and sweep the floor and
23 } ,
24
25 {
26 "name" : "Nested Blockquotes",
27 "description" : "Blockquotes can be nested. Add a `>>` in front of the paragraph you want to nest.",
28 "markdown" : "> Dorothy followed her through many of the beautiful rooms in her castle.\n>\n>> The Witch bade her clean the pots and kettles and sweep the floor and keep the fi
29 "html" : "<blockquote><p>Dorothy followed her through many of the beautiful rooms in her castle.</p><blockquote><p>The Witch bade her clean the pots and kettles and sweep t
30 } ,
31
32 {
33 "name" : "Blockquotes with Other Elements",
34 "description" : "Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you'll need to experiment to see which ones work.",
35 "markdown" : "> ### The quarterly results look great!\n>\n> - Revenue was off the chart.\n> - Profits were higher than ever.\n>\n> *Everything* is going according to **plan**.
36 "html" : "<blockquote><h3>The quarterly results look great!</h3><ul><li>Revenue was off the chart.</li><li>Profits were higher than ever.</li></ul><p><em>Everything</em> is
37 }
38
39 ]
40 } ,
41 {
42 "name" : "Bold",
43 "description" : "To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks without spaces around the
44 "examples" : [
45
46 {
47 "markdown" : "I just love **bold text**.",
48 "html" : "I just love <strong>bold text</strong>."
49 } ,
50
51 {
52 "markdown" : "I just love __bold text__.",
53 "html" : "I just love <strong>bold text</strong>."
54 } ,
55
56 {
57 "markdown" : "Love**is**bold",
58 "html" : "Love<strong>is</strong>bold"
59 }
60
61 ],
63
64 ]
65 } ,
66 {
67 "name" : "Code",
68 "description" : "To denote a word or phrase as code, enclose it in tick marks (`` ` ``).",
69 "examples" : [
70
71 {
72 "markdown" : "At the command prompt, type `nano`.",
73 "html" : "At the command prompt, type <code>nano</code>."
74 }
75
76 ],
78
79 {
80 "name" : "Escaping Tick Marks",
81 "description" : "If the word or phrase you want to denote as code includes one or more tick marks, you can escape it by enclosing the word or phrase in double tick marks (<code>``
82 "markdown" : "``Use `code` in your Markdown file.``",
83 "html" : "<code>Use `code` in your Markdown file.</code>"
84 } ,
85
86 {
87 "name" : "Code Blocks",
88 "description" : "To create code blocks, indent every line of the block by at least four spaces or one tab.",
89 "markdown" : "<html>\n <head>\n </head>\n</html>\n",
90 "html" : "<pre><code><html><head></head></html></code></pre>"
91 }
92
93 ]
94 } ,
95 {
96 "name" : "Headings",
97 "description" : "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 cre
98 "examples" : [
99
100 {
101 "markdown" : "# Heading level 1",
102 "html" : "<h1>Heading level 1</h1>"
103 } ,
104
105 {
106 "markdown" : "## Heading level 2",
108 } ,
109
110 {
111 "markdown" : "### Heading level 3",
113 } ,
114
115 {
116 "markdown" : "#### Heading level 4",
118 } ,
119
120 {
121 "markdown" : "##### Heading level 5",
123 } ,
124
125 {
126 "markdown" : "###### Heading level 6",
128 }
129
130 ],
132
133 {
134 "name" : "Alternative H1 Syntax",
135 "description" : "Alternatively, on the line below the text, add any number of == characters for heading level 1.",
136 "markdown" : "Heading level 1\n===============\n",
138 } ,
139
140 {
141 "name" : "Alternative H2 Syntax",
142 "description" : "Alternatively, on the line below the text, add any number of -- characters for heading level 2.",
143 "markdown" : "Heading level 2\n---------------\n",
145 }
146
147 ]
148 } ,
149 {
150 "name" : "Horizontal Rules",
151 "description" : "To create a horizontal rule, use three or more asterisks (`***`), dashes (`---`), or underscores (`___`) on a line by themselves.",
152 "examples" : [
153
154 {
155 "markdown" : "***",
156 "html" : "<hr>"
157 } ,
158
159 {
160 "markdown" : "---",
161 "html" : "<hr>"
162 } ,
163
164 {
165 "markdown" : "_________________",
166 "html" : "<hr>"
167 }
168
169 ],
171
172 ]
173 } ,
174 {
175 "name" : "Images",
176 "description" : "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
177 "examples" : [
178
179 {
180 "markdown" : "![Philadelphia's Magic Gardens. This place was so cool!](/assets/images/philly-magic-gardens.jpg \"Philadelphia's Magic Gardens\")\n",
181 "html" : "<img src=\"/assets/images/philly-magic-garden.jpg\" class=\"img-responsive\" alt=\"Philadelphia's Magic Gardens. This place was so cool!\" title=\"Philadelphia's
182 }
183
184 ],
186
187 {
188 "name" : "Linking Images",
189 "description" : "To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses.",
190 "markdown" : "[![An old rock in the desert](/assets/images/shiprock.jpg \"Shiprock, New Mexico by Beau Rogers\")](https://www.flickr.com/photos/beaurogers/31833779864/in/photol
191 "html" : "<a href=\"https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F-a9Cmfy-5Ha3Zi-9msKdv-o3hgjr-hWpUte-4WMsJ1-KUQ8N-deshUb-vssBD-6CQci6-8AFC
192 }
193
194 ]
195 } ,
196 {
197 "name" : "Italic",
198 "description" : "To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces aro
199 "examples" : [
200
201 {
202 "markdown" : "Italicized text is the *cat's meow*.",
203 "html" : "Italicized text is the <em>cat's meow</em>."
204 } ,
205
206 {
207 "markdown" : "Italicized text is the _cat's meow_.",
208 "html" : "Italicized text is the <em>cat's meow</em>."
209 } ,
210
211 {
212 "markdown" : "A*cat*meow",
213 "html" : "A<em>cat</em>meow"
214 }
215
216 ],
218
219 ]
220 } ,
221 {
222 "name" : "Line Breaks",
223 "description" : "To create a line break (`<br>`), end a line with two or more spaces, and then type return.",
224 "examples" : [
225
226 {
227 "markdown" : "This is the first line. \nAnd this is the second line.\n",
228 "html" : "<p>This is the first line. <br>And this is the second line.</p>"
229 }
230
231 ],
233
234 ]
235 } ,
236 {
237 "name" : "Links",
238 "description" : "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)
239 "examples" : [
240
241 {
242 "markdown" : "My favorite search engine is [Duck Duck Go](https://duckduckgo.com \"The best search engine for privacy\").",
243 "html" : "My favorite search engine is <a href=\"https://duckduckgo.com\" title=\"The best search engine for privacy\">Duck Duck Go</a>."
244 }
245
246 ],
248
249 {
250 "name" : "URLs and Email Addresses",
251 "description" : "To quickly turn a URL or email address into a link, enclose it in angle brackets.",
252 "markdown" : "<https://www.markdownguide.org><fake@example.com>",
253 "html" : "<a href=\"https://www.markdownguide.org\">https://www.markdownguide.org</a><a href=\"mailto:fake@e&#
254 } ,
255
256 {
257 "name" : "Formatting Links",
258 "description" : "To emphasize links, add asterisks before and after the brackets and parentheses.",
259 "markdown" : "I love supporting **[EFF](https://eff.org)**. This is the *[Markdown Guide](https://www.markdownguide.org)*.",
260 "html" : "I love supporting <strong><a href=\"https://eff.org\">EFF</a></strong>. This is the <em><a href=\"https://www.markdownguide.org\">Markdown Guide</a></em>."
261 }
262
263 ]
264 } ,
265 {
266 "name" : "Ordered Lists",
267 "description" : "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 o
268 "examples" : [
269
270 {
271 "markdown" : "1. First item\n2. Second item\n3. Third item\n4. Fourth item\n",
272 "html" : "<ol><li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ol>"
273 } ,
274
275 {
278 } ,
279
280 {
283 } ,
284
285 {
286 "markdown" : "1. First item\n2. Second item\n3. Third item\n 1. Indented item\n 2. Indented item\n4. Fourth item\n",
287 "html" : "<ol><li>First item</li><li>Second item</li><li>Third item<ol><li>Indented item</li><li>Indented item</li></ol></li><li>Fourth item</li></ol>"
288 }
289
290 ],
292
293 ]
294 } ,
295 {
296 "name" : "Paragraphs",
297 "description" : "To create paragraphs, use a blank line to separate one or more lines of text. You should not indent paragraphs with spaces or tabs.",
298 "examples" : [
299
300 {
301 "markdown" : "I really like using Markdown.\n\nI think I'll use it to format all of my documents from now on.\n",
302 "html" : "<p>I really like using Markdown.</p><p>I think I'll use it to format all of my documents from now on.</p>"
303 }
304
305 ],
307
308 ]
309 } ,
310 {
311 "name" : "Unordered Lists",
312 "description" : "To create an unordered list, add dashes (`-`), asterisks (`*`), or plus signs (`+`) in front of line items. Indent one or more items to create a nested list.",
313 "examples" : [
314
315 {
316 "markdown" : "- First item\n- Second item\n- Third item\n- Fourth item\n",
317 "html" : "<ul><li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ul>"
318 } ,
319
320 {
321 "markdown" : "* First item\n* Second item\n* Third item\n* Fourth item\n",
323 } ,
324
325 {
326 "markdown" : "+ First item\n* Second item\n- Third item\n+ Fourth item\n",
328 } ,
329
330 {
331 "markdown" : "- First item\n- Second item\n- Third item\n - Indented item\n - Indented item\n- Fourth item\n",
332 "html" : "<ul><li>First item</li><li>Second item</li><li>Third item<ul><li>Indented item</li><li>Indented item</li></ul></li><li>Fourth item</li></ul>"
333 }
334
335 ],
337
338 ]
339 }
340 ]
341 }
basic-syntax.json hosted with ❤ by GitHub view raw
Cheat Sheet Endpoint

The cheat sheet endpoint provides an overview of the most popular basic and extended Markdown syntax
elements, as described on the Cheat Sheet page.
API Endpoint
/api/v1/cheat-sheet.json
Request
curl https://www.markdownguide.org/api/v1/cheat-sheet.json
Response
1 {
2 "status": "OK",
3 "last_updated": "2017-11-10",
4 "cheat_sheet": [
5 {
6 "basic_syntax": [
7
8 {
9 "element" : "Blockquotes",
10 "syntax" : "> blockquote"
11 } ,
12
13 {
14 "element" : "Bold",
15 "syntax" : "**bold text**"
16 } ,
17
18 {
19 "element" : "Code",
20 "syntax" : "`code`"
21 } ,
22
23 {
24 "element" : "Headings",
25 "syntax" : "# H1\n## H2\n### H3\n"
26 } ,
27
28 {
29 "element" : "Horizontal Rules",
30 "syntax" : "---"
31 } ,
32
33 {
34 "element" : "Images",
35 "syntax" : "![alt text](image.jpg)"
36 } ,
37
38 {
39 "element" : "Italic",
40 "syntax" : "*italicized text*"
41 } ,
42
43 {
44 "element" : "Links",
45 "syntax" : "[title](https://www.example.com)"
46 } ,
47
48 {
49 "element" : "Ordered Lists",
50 "syntax" : "1. First item\n2. Second item\n3. Third item\n"
51 } ,
52
53 {
54 "element" : "Unordered Lists",
55 "syntax" : "- First item\n- Second item\n- Third item\n"
56 }
57
58 ]
59 },
60 {
61 "extended_syntax": [
62
63 {
64 "element" : "Definition Lists",
65 "syntax" : "term\n: definition\n"
66 } ,
67
68 {
69 "element" : "Fenced Code Blocks",
70 "syntax" : "```\n{\n\"firstName\": \"John\",\n\"lastName\": \"Smith\",\n\"age\": 25\n}\n```\n"
71 } ,
72
73 {
74 "element" : "Footnotes",
75 "syntax" : "Here's a sentence with a footnote. [^1]\n\n[^1]: This is the footnote.\n"
76 } ,
77
78 {
79 "element" : "Heading IDs",
80 "syntax" : "### My Great Heading {#custom-id}"
81 } ,
82
83 {
84 "element" : "Strikethrough",
85 "syntax" : "~~The world is flat.~~"
86 } ,
87
88 {
89 "element" : "Tables",
90 "syntax" : "| Syntax | Description |\n| ----------- | ----------- |\n| Header | Title |\n| Paragraph | Text |\n"
91 } ,
92
93 {
94 "element" : "Task Lists",
95 "syntax" : "- [x] Write the press release\n- [ ] Update the website\n- [ ] Contact the media\n"
96 }
97
98 ]
99 }
100 ]
101 }
cheat-sheet.json hosted with ❤ by GitHub view raw
Changelog
Here’s a list of all the changes we’ve made to the Markdown Guide API.
2018-10-18
- Updated cheat sheet endpoint to include information about definition lists
2018-07-12
- Updated links description to include information about adding titles
2017-11-10
- Added cheat sheet endpoint
2017-11-04
- Added section about escaping backticks in code
2017-10-24
- Released API v1
- Published docs
Take your Markdown skills to the next level.

Learn Markdown in 60 pages. Designed for both novices and experts, The
Markdown Guide book is a comprehensive reference that has everything you
need to get started and master Markdown syntax.
Get the Book
Want to learn more Markdown?
Don't stop now! Star the GitHub repository and then enter your email address below to receive new
Markdown tutorials via email. No spam!
Your email address
Stay updated
Reach specific
developers on the
open source, privacy-
About Contact GitHub API Privacy Policy Terms and Conditions first ad network:
EthicalAds
© 2024. A Matt Cone project. CC BY-SA 4.0. Made with in New Mexico.
Ads by EthicalAds

Markdown Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Markdown Guide

Uploaded by

Copyright:

Available Formats

Overview

Element Markdown Syntax

Bold **bold text**

Italic *italicized text*

Blockquote > blockquote

Ordered List 1. First item

Unordered List - First item

Horizontal Rule ---

Image ![alt text](image.jpg)

Element Markdown Syntax

Table | Syntax | Description |

Fenced Code Block ```

Footnote Here's a sentence with a footnote. [^1]

[^1]: This is the footnote.

Heading ID ### My Great Heading {#custom-id}

Definition List term

Strikethrough ~~The world is flat.~~

Task List - [x] Write the press release

Emoji That is so funny! :joy:

Highlight I need to highlight these ==very important words==.

Why Use Markdown?

What’s Markdown Good For?

Why Use Markdown?

Kicking the Tires

How Does it Work?

To summarize, this is a four-part process:

What’s Markdown Good For?

Here are some examples of what you can do with Markdown.

Here are some Markdown document authoring applications I recommend:

Mac: MacDown, iA Writer, or Marked 2

Obsidian is a popular Markdown note-taking application loaded with features.

#### Heading level 4 <h4>Heading level 4</h4>

##### Heading level 5 <h5>Heading level 5</h5>

###### Heading level 6 <h6>Heading level 6</h6>

Markdown HTML Rendered Output

Heading level 1 <h1>Heading level 1</h1>

Heading Best Practices

Do this Don't do this

# Here's a Heading #Here's a Heading

Do this Don't do this

...and after a heading.

Markdown HTML Rendered Output

Paragraph Best Practices

Do this Don't do this

Markdown HTML Rendered Output

Line Break Best Practices

Do this Don't do this

Markdown HTML Rendered Output

Love**is**bold Love<strong>is</strong>bold Loveisbold

Bold Best Practices

Do this Don't do this

Markdown HTML Rendered Output

A*cat*meow A<em>cat</em>meow Acatmeow

Italic Best Practices

Do this Don't do this

Bold and Italic

Markdown HTML Rendered Output

This text is ***really This text is <em><strong>really This text is really

This text is ___really This text is <em><strong>really This text is really

This text is __*really This text is <em><strong>really This text is really

This text is **_really This text is <em><strong>really This text is really

This is This is really<em><strong>very</strong> This is

Bold and Italic Best Practices

Do this Don't do this

Bold bold text

Italic italicized text

Strikethrough The world is flat.

Loveisbold Love<strong>is</strong>bold Loveisbold

Acatmeow A<em>cat</em>meow Acatmeow

This is reallyveryimportant text. This is really_very_important text.