. and after a heading.

I think I’ll use it to format all of my documents from now on.

First line with the HTML tag after.

And the next line.

First line with nothing after.
And the next line.

Emphasis

You can add emphasis by making text bold or italic.

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.

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.

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.

Italic Best Practices

Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to italicize the middle of a word for emphasis.

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.

Bold and Italic Best Practices

Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to bold and italicize the middle of a word for emphasis.

Blockquotes

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

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 rendered output looks like this:

Dorothy followed her through many of the beautiful rooms in her castle.

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 rendered output looks like this:

Dorothy followed her through many of the beautiful rooms in her castle.

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 rendered output looks like this:

The quarterly results look great!

Everything is going according to plan.

Blockquotes Best Practices

For compatibility, put blank lines before and after blockquotes.

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.

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.

Unordered Lists

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.

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.

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.

Paragraphs

The rendered output looks like this:

Here’s the second list item.

I need to add another paragraph below the second list item.

Blockquotes

The rendered output looks like this:

Here’s the second list item.

A blockquote would look great below the second 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.

The rendered output looks like this:

Find the following code block on line 21:

Images

The rendered output looks like this:

Marvel at its beauty.

Lists

You can nest an unordered list in an ordered list, or vice versa.

The rendered output looks like this:

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

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 ( « ).

Code Blocks

To create code blocks, indent every line of the block by at least four spaces or one tab.

The rendered output looks like this:

Horizontal Rules

The rendered output of all three looks identical:

Horizontal Rule Best Practices

For compatibility, put blank lines before and after horizontal rules.

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) ).

The rendered output looks like this:

My favorite search engine is Duck Duck Go.

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.

The rendered output looks like this:

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.

The rendered output looks like this:

Formatting Links

To emphasize links, add asterisks before and after the brackets and parentheses. To denote links as code, add backticks in the brackets.

The rendered output looks like this:

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:

Formatting the Second Part of the Link

The second part of a reference-style link is formatted with the following attributes:

This means the following example formats are all roughly equivalent for the second part of the link:

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:

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 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:

Link Best Practices

Images

The rendered output looks like this:

Linking Images

To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses.

The rendered output looks like this:

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.

The rendered output looks like this:

* 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.

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.

The rendered output looks like this:

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

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,

italic and **bold**

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.

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!

Markdown code block

Note: This document is itself written using Markdown; you can see the source for it by adding ‘.md’ to the URL.

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Automatic Escaping for Special Characters

Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ‘ AT&T ‘. You even need to escape ampersands within URLs. Thus, if you want to link to:

you need to encode the URL as:

in your anchor tag href attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

So, if you want to include a copyright symbol in your article, you can write:

and Markdown will leave it alone. But if you write:

Markdown will translate it to:

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

Markdown will translate it to:

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single and & in your example code needs to be escaped.)

Paragraphs and Line Breaks

The implication of the «one or more consecutive lines of text» rule is that Markdown supports «hard-wrapped» text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s «Convert Line Breaks» option) which translate every line break character in a paragraph into a
tag.

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Markdown supports two styles of headers, [Setext] 1 and [atx] 2.

Setext-style headers are «underlined» using equal signs (for first-level headers) and dashes (for second-level headers). For example:

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

Markdown uses email-style > characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of > :

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

Markdown supports ordered (numbered) and unordered (bulleted) lists.

is equivalent to:

Ordered lists use numbers followed by periods:

It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

If you instead wrote the list in Markdown like this:

you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

But if you want to be lazy, you don’t have to:

If list items are separated by blank lines, Markdown will wrap the items in

tags in the HTML output. For example, this input:

Markdown code block

Copy raw contents

Most of the examples from this documentation are in Markdown. Markdown is default parser for GitBook, but one can also opt for the AsciiDoc syntax.

Here’s an overview of Markdown syntax that you can use with GitBook (same as GitHub with some additions).

To create a heading, add one to six # symbols before your heading text. The number of # you use will determine the size of the heading.

GitBook supports a nice way for explicitly setting the header ID. If you follow the header text with an opening curly bracket (separated from the text with a least one space), a hash, the ID and a closing curly bracket, the ID is set on the header. If you use the trailing hash feature of atx style headers, the header ID has to go after the trailing hashes. For example:

Paragraphs and Line Breaks

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line — a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use asterisks, pluses, and hyphens — interchangably — as list markers:

Ordered lists use numbers followed by periods:

Markdown supports two style of links: inline and reference.

A simple link can be created by surrounding the text with square brackets and the link URL with parentheses:

Links can point to relative paths, anchors or absolute urls.

There is another way to create links which does not interrupt the text flow. The URL and title are defined using a reference name and this reference name is then used in square brackets instead of the link URL:

Then, anywhere in the document, you define your link label like this, on a line by itself:

Images can be created in a similar way than links: just use an exclamation mark before the square brackets. The link text will become the alternative text of the image and the link URL specifies the image source:

A blockquote is started using the > marker followed by an optional space; all following lines that are also started with the blockquote marker belong to the blockquote. You can use any block-level elements inside a blockquote:

The pipes on either end of the table are optional. Cells can vary in width and do not need to be perfectly aligned within columns. There must be at least three hyphens in each column of the header row.

Markdown supports two different code block styles. One uses lines indented with either four spaces or one tab whereas the other uses lines with tilde characters as delimiters – therefore the content does not need to be indented:

Fenced code blocks

You can create fenced code blocks by placing triple backticks «` before and after the code block. We recommend placing a blank line before and after code blocks to make the raw formatting easier to read.

You can add an optional language identifier to enable syntax highlighting in your fenced code block.

For example, to syntax highlight Ruby code:

Text phrases can be marked up as code by surrounding them with backticks:

GitBook supports a simple syntax for such footnotes. Footnotes are relative to each pages.

GitBook supports use of raw HTML in your text, Markdown syntax in HTML is not processed:

Horizontal Rules can be inserted using three or more asterisks, dashes or underscores, optionally separated by spaces or tabs, on an otherwise blank line:

Ignoring Markdown formatting

You can tell GitBook to ignore (or escape) Markdown formatting by using \ before the Markdown character.

VEnis / gist:7465176

Note: This document is itself written using Markdown; you can see the source for it by adding ‘.text’ to the URL.

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Automatic Escaping for Special Characters

Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ‘ AT&T ‘. You even need to escape ampersands within URLs. Thus, if you want to link to:

you need to encode the URL as:

in your anchor tag href attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

So, if you want to include a copyright symbol in your article, you can write:

and Markdown will leave it alone. But if you write:

Markdown will translate it to:

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

Markdown will translate it to:

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single and & in your example code needs to be escaped.)

Paragraphs and Line Breaks

The implication of the «one or more consecutive lines of text» rule is that Markdown supports «hard-wrapped» text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s «Convert Line Breaks» option) which translate every line break character in a paragraph into a
tag.

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Markdown supports two styles of headers, [Setext] 1 and [atx] 2.

Setext-style headers are «underlined» using equal signs (for first-level headers) and dashes (for second-level headers). For example:

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

Markdown uses email-style > characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of > :

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

Markdown supports ordered (numbered) and unordered (bulleted) lists.

is equivalent to:

Ordered lists use numbers followed by periods:

It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

If you instead wrote the list in Markdown like this:

you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

But if you want to be lazy, you don’t have to:

If list items are separated by blank lines, Markdown will wrap the items in

tags in the HTML output. For example, this input:

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab:

It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:

To put a blockquote within a list item, the blockquote’s > delimiters need to be indented:

It’s worth noting that it’s possible to trigger an ordered list by accident, by writing something like this:

In other words, a number-period-space sequence at the beginning of a line. To avoid this, you can backslash-escape the period:

Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both

Markdown will generate:

A code block continues until it reaches a line that is not indented (or the end of the article).

Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use Markdown to write about Markdown’s own syntax.

You can produce a horizontal rule tag ( ) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

Markdown supports two style of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

If you’re referring to a local resource on the same server, you can use relative paths:

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

You can optionally use a space to separate the sets of brackets:

Then, anywhere in the document, you define your link label like this, on a line by itself:

The following three link definitions are equivalent:

Note: There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.

The link URL may, optionally, be surrounded by angle brackets:

You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.

And then define the link:

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

And then define the link:

Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they’re used, but if you want, you can put them all at the end of your document, sort of like footnotes.

Here’s an example of reference links in action:

Using the implicit link name shortcut, you could instead write:

Both of the above examples will produce the following HTML output:

For comparison, here is the same paragraph written using Markdown’s inline link style:

The point of reference-style links is not that they’re easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it’s 176 characters; and as raw HTML, it’s 234 characters. In the raw HTML, there’s more markup than there is text.

With Markdown’s reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.

Markdown treats asterisks ( * ) and underscores ( _ ) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML tag; double * ‘s or _ ‘s will be wrapped with an HTML tag. E.g., this input:

You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.

Emphasis can be used in the middle of a word:

But if you surround an * or _ with spaces, it’ll be treated as a literal asterisk or underscore.

To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:

To indicate a span of code, wrap it with backtick quotes ( ` ). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

which will produce this:

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this:

You can write this:

Admittedly, it’s fairly difficult to devise a «natural» syntax for placing images into a plain text document format.

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline image syntax looks like this:

Reference-style image syntax looks like this:

Where «id» is the name of a defined image reference. Image references are defined using syntax identical to link references:

As of this writing, Markdown has no syntax for specifying the dimensions of an image; if this is important to you, you can simply use regular HTML tags.

Markdown supports a shortcut style for creating «automatic» links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:

Markdown will turn this into:

Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this:

into something like this:

which will render in a browser as a clickable link to «address@example.com».

(This sort of entity-encoding trick will indeed fool many, if not most, address-harvesting bots, but it definitely won’t fool all of them. It’s better than nothing, but an address published in this way will probably eventually start receiving spam.)

Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML tag), you can use backslashes before the asterisks, like this:

Markdown provides backslash escapes for the following characters:

Markdown code block

Copy raw contents

Markdown is a easy-to-use markup language for writing and this document contains all supported markdown features.

Table of contents

Headings from h1 through h6 are constructed with a # for each level:

Alternatively you can use underlines:

Just write normal text:

You can use multiple consecutive newline characters ( \n ) to create extra spacing between sections in a markdown document. However, if you need to ensure that extra newlines are not collapsed, you can use as many HTML
elements as you want.

Alternatively you can add two spaces spaces at the end of your paragraph to force a soft linebreak.

The HTML element is for creating a «thematic break» between paragraph-level elements. In markdown, you can use of the following for this purpose:

For emphasizing a snippet of text with a heavier font-weight.

The following snippet of text is rendered as bold text.

rendered as bold text

For emphasizing a snippet of text with italics.

The following snippet of text is rendered as italicized text.

rendered as italicized text

In GFM you can do strickthroughs by wrapping the text with double tildes.

Which renders to:

Strike through this text.

URIs or email addresses that are not wrapped in angle brackets are not recognized as valid autolinks by markdown parsers.

Renders to (hover over the link, there is no tooltip):

Renders to (hover over the link, there should be a tooltip):

Named anchors enable you to jump to the specified anchor point on the same page. For example, each of these chapters:

will jump to these sections:

Anchor placement

Note that placement of achors is arbitrary, you can put them anywhere you want, not just in headings. This makes adding cross-references easy when writing markdown.

Images have a similar syntax to links but include a preceding exclamation point.

Like links, Images also have a footnote style syntax

With a reference later in the document defining the URL location:

Used for defining a section of quoting text from another source, within your document.

To create a blockquote, use > before any text you want to quote.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

Blockquotes can also be nested:

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.

Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.

A list of items in which the order of the items does not explicitly matter.

You may use any of the following symbols to denote bullets for each list item:

A list of items in which the order of items does explicitly matter.

Sometimes lists change, and when they do it’s a pain to re-order all of the numbers. Markdown solves this problem by allowing you to simply use 1. before each item in the list.

Automatically re-numbers the items and renders to:

Links in todo lists

Tables are created by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header (this line of dashes is required).

Center text in a column

To center the text in a column, add a colon to the left and right of the dashes in the row beneath the header.

Right-align the text in a column

To right-align the text in a column, add a colon to the right of the dashes in the row beneath the header.

For example, to show

«Fenced» code block

For example, this:

Appears like this when viewed in a browser:

You may also indent several lines of code by at least four spaces, but this is not recommended as it is harder to read, harder to maintain, and doesn’t support syntax highlighting.

Which renders to:

Github-Flavored Markdown (GFM) allows you to highlight keyboard keys.

For example, this:

Which renders to:

To copy, please press CmdOrCtrl + C

To paste, please press CmdOrCtrl + V

Github-Flavored Markdown (GFM) supports also Emojis. 😍 😄 😂

To add an emojis, just surround the emoji name with colons, like this:

Which renders to:

NOTE: MarkText provides an emoji picker with search functionality.

Front matter allows you to insert metadata to your markdown document. The front matter block must be written in the first line before everything else, like in the examples below.

TOML front matter blocks are identified by an opening and closing +++ line.

JSON front matter blocks are identified by an opening and closing ;;; line or < and >.

Inline Math Formulas

Block Math Formulas

For example, this:

MarkText support class, flow chart, gantt and sequence diagrams powered by flowchart.js, mermaid and Vega-Lite. Code blocks with special language identifiers are used for diagrams.

For example, this:

Please visit PlantUML website for more details.

Any text between and > that looks like an HTML tag will be parsed as a raw HTML tag and rendered to HTML without escaping.

Escaping with backslashes

Any ASCII punctuation character may be escaped using a single backslash.

*this is not italic*

This markdown cheatsheet was created by @jonschlinkert and modified. The source can be found here.

Footer

© 2022 GitHub, Inc.

You can’t perform that action at this time.

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.

safe1981 / gist:2019322

Note: This document is itself written using Markdown; you can see the source for it by adding ‘.text’ to the URL.

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Automatic Escaping for Special Characters

Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ‘ AT&T ‘. You even need to escape ampersands within URLs. Thus, if you want to link to:

you need to encode the URL as:

in your anchor tag href attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

So, if you want to include a copyright symbol in your article, you can write:

and Markdown will leave it alone. But if you write:

Markdown will translate it to:

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

Markdown will translate it to:

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single and & in your example code needs to be escaped.)

Paragraphs and Line Breaks

The implication of the «one or more consecutive lines of text» rule is that Markdown supports «hard-wrapped» text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s «Convert Line Breaks» option) which translate every line break character in a paragraph into a
tag.

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Markdown supports two styles of headers, [Setext] 1 and [atx] 2.

Setext-style headers are «underlined» using equal signs (for first-level headers) and dashes (for second-level headers). For example:

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

Markdown uses email-style > characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of > :

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

Markdown supports ordered (numbered) and unordered (bulleted) lists.

is equivalent to:

Ordered lists use numbers followed by periods:

It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

If you instead wrote the list in Markdown like this:

you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

But if you want to be lazy, you don’t have to:

If list items are separated by blank lines, Markdown will wrap the items in

tags in the HTML output. For example, this input:

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab:

It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:

To put a blockquote within a list item, the blockquote’s > delimiters need to be indented:

It’s worth noting that it’s possible to trigger an ordered list by accident, by writing something like this:

In other words, a number-period-space sequence at the beginning of a line. To avoid this, you can backslash-escape the period:

Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both

Markdown will generate:

A code block continues until it reaches a line that is not indented (or the end of the article).

Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use Markdown to write about Markdown’s own syntax.

You can produce a horizontal rule tag ( ) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

Markdown supports two style of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

If you’re referring to a local resource on the same server, you can use relative paths:

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

You can optionally use a space to separate the sets of brackets:

Then, anywhere in the document, you define your link label like this, on a line by itself:

The following three link definitions are equivalent:

Note: There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.

The link URL may, optionally, be surrounded by angle brackets:

You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.

And then define the link:

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

And then define the link:

Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they’re used, but if you want, you can put them all at the end of your document, sort of like footnotes.

Here’s an example of reference links in action:

Using the implicit link name shortcut, you could instead write:

Both of the above examples will produce the following HTML output:

For comparison, here is the same paragraph written using Markdown’s inline link style:

The point of reference-style links is not that they’re easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it’s 176 characters; and as raw HTML, it’s 234 characters. In the raw HTML, there’s more markup than there is text.

With Markdown’s reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.

Markdown treats asterisks ( * ) and underscores ( _ ) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML tag; double * ‘s or _ ‘s will be wrapped with an HTML tag. E.g., this input:

You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.

Emphasis can be used in the middle of a word:

But if you surround an * or _ with spaces, it’ll be treated as a literal asterisk or underscore.

To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:

To indicate a span of code, wrap it with backtick quotes ( ` ). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

which will produce this:

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this:

You can write this:

Admittedly, it’s fairly difficult to devise a «natural» syntax for placing images into a plain text document format.

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline image syntax looks like this:

Reference-style image syntax looks like this:

Where «id» is the name of a defined image reference. Image references are defined using syntax identical to link references:

As of this writing, Markdown has no syntax for specifying the dimensions of an image; if this is important to you, you can simply use regular HTML tags.

Markdown supports a shortcut style for creating «automatic» links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:

Markdown will turn this into:

Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this:

into something like this:

which will render in a browser as a clickable link to «address@example.com».

(This sort of entity-encoding trick will indeed fool many, if not most, address-harvesting bots, but it definitely won’t fool all of them. It’s better than nothing, but an address published in this way will probably eventually start receiving spam.)

Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML tag), you can use backslashes before the asterisks, like this:

Markdown provides backslash escapes for the following characters:

Markdown Extended Syntax

Advanced features based on the foundations of Markdown.

Introduction

The original Markdown syntax, published by John Gruber, added several essential elements for editing documents, but some users were not satisfied.

The extended syntax tries to resolve this dissatisfaction by adding new elements through new markups.

Tables, code blocks, automatic links generation and even footnotes are examples of extending the Markdown basic syntax.

These elements can be activated by installing a plugin for your Markdown processor or even using a small variation of the language.

NOTE: it is quite possible that your Markdown application already has support for the elements presented in this article, so it is worth testing each one of them while following the tutorial.

Flavors of Markdown

photo Markdown flavors

Markdown has a few different flavors, in other words, variations of the language basic syntax.

These variations, in addition to supporting basic syntax, add elements that enrich the document editing.

Applications compatible with Markdown will often use one of the languages presented below:

Creating tables in Markdown

A table in Markdown can be used to present data comparisons by the user.

photo Tables in Markdown

Below is an example table:

The vertical bars | used at the ends of the table are for purely cosmetic purposes, the table can be created without adding the side bars.

The output rendered in HTML:

The width of the cells, within a Markdown table, can vary.

Generating tables in Markdown automatically

Markdown came to make document editing easier, and creating tables can become a bit more tedious.

The use of vertical bars and dashes may displease some users, so it is interesting that we can automate the process of formatting tables in Markdown.

photo Table structure in Markdown generated automatically.

Alignment

Markdown allows you to align the contents of a table column to the left, right or center.

NOTE: Using the colon to align the text to the left is optional, as the table contents are already aligned in that position by default.

To align the contents of the column to the center in a Markdown table, add a colon : before and after the dashes that separate the header line.

It is possible to merge the alignment formatting, since it only influences the content inside the column.

NOTE: The contents of the table header will also be aligned according to the position of the colon.

Formatting text in tables

You can insert some basic elements of Markdown inside a table.

Titles, code blocks, blockquotes, lists, horizontal rules, images and HTML tags do not work.

NOTE: You may find applications that accept the insertion of the elements mentioned above inside a table, but this will harm the portability of your document, since other programs do not support it.

Escaping vertical bars in tables

photo Escaping a vertical bar inside the table in Markdown

Fenced code block

A surrounded code block allows you to create code representations without having to indent the line in four spaces or a tab, in addition, it also allows you to define which programming language the block represents, with this, it is possible to apply the appropriate syntax highlighting.

To create a fenced code block in Markdown, place three backticks «` before the content and three backticks «` after the content.

The rendered output looks like this:

NOTE: Some Markdown processors allow you to use tildes

instead of backticks to form the fenced code block.

Syntax highlighting

Many JavaScript libraries are used to highlight code blocks, such as: Prism.js & highlight.js.

They take a specific HTML tag, usually the pre or code tag and apply highlighting based on the syntax of the code block’s programming language.

The language syntax is usually defined by the parameter class of tag, for example:

NOTE: The highlighting process can be done automatically, some tools have the ability to detect the programming languages ​​in an automated way, without the need to define the language in the class parameter.

As in the first line of the block, just after the three opening backticks, json was specified, the code will be highlighted accordingly:

NOTE: the code will only be highlighted if you use a JavaScript library that performs this type of task, HTML itself does not highlight the code.

Footnotes

A footnote in Markdown allows the user to create a reference to some concept mentioned in the document.

Typically, these footnotes are placed at the end of the document, but in Markdown you can define them anywhere in the text.

When creating a footnote a superscript number in the form of link will be inserted in the location that you created it, when the user clicks on that link it will be taken directly to the location that contains the reference of the note.

The syntax for creating the footnote is divided into two parts.

The identifier can contain numbers and letters, but does not accept spaces or tabs.

The rendering in golkie itc looks like this:

This is the first footnote. ↩

Here is one with several paragraphs and code.

Indent paragraphs to include them in the footnote.

Add as many paragraphs as you want. ↩

NOTE: The content of the footer can be placed anywhere in the document except inside other Markdown elements such as tables, lists and code blocks.

NOTE: Footnotes will always be numbered sequentially, regardless of the identifiers you created, a sequence of notes [^35], [^yyyy] and [^102_444], will be rendered as 1, 2 and 3.

Adding ID or Class to Markdown elements

With id we can get a specific reference for a particular element, normally the element’s id is unique within the HTML markup.

The parameter class is generic and can be assigned to several elements.

The function of id or class is to allow you to easily recognize these elements through JavaScript or CSS, using this id or this class we can handle properties such as color, size, placement, etc.

The HTML looks like this:

Links for ids in Markdown

If the id is in another document, the formatting is similar, however, before identification, place the page URL.

Definition Lists

The HTML looks like this:

First term This is the definition of the first term. Second term This is a definition of the second term. This is another definition of the second term.

Strikethrough in Markdown

The strikethrough is used to correct an error comparatively, usually followed by correction on the same line.

The strikethrough is nothing more than a format that inserts a horizontal line in the middle of a piece of content.

To apply the strikethrough formatting to a content in Markdown use two tildes

before and after the text.

And the result is this:

Markdown is: difficult easy to learn.

Task lists in Markdown

The rendered output looks like this:

photo Task List in Markdown

Inserting Emojis in the Markdown document

Yes, you can insert the famous emoticons directly in the Markdown formatting of your document.

photo Emojis on Markdown

There are two most commonly used ways for the task, copying and pasting the emoji into the content or entering emoji codes.

We will understand better how the two procedures work, but first, click here to open our Markdown editor and test the emojis in real time.

Copying and pasting Emojis in Markdown

NOTE: You can explore Emojipedia to find your favorite emoji, the copy and paste procedure is the same for all of them.

If your Markdown application is compatible, you will see the representation of the emoticon directly in the text.

When converting the Markdown document to HTML or even PDF, the emojis are still represented correctly.

NOTE: If the HTML document is not rendering the emojis the way it should, encode the pages in UTF-8.

Using Emoji access codes

An emoji code is formed by identifying the emoticon surrounded by a colon.

To insert an emoji in Markdown using access code, place the emoticon code in between colons.

The rendered output looks like this:

I went camping! ⛺ I’ll be back soon.

This is so funny! 😂

Discovering the Emojis access code

If you don’t know the emoji access code, use our Markdown editor to find out.

In the left panel you can see the emoji code and in the right panel the rendering.

NOTE: The images of emoticons can vary greatly from application to application, in this list you find the emojis compatible with Markdown used by GitHub, you can test them in your application to find out if there are compatibility.

Automatic linking URLs in Markdown

Some Markdown processors turn URL into links when they find an address between the less than and greater than > signs.

On other occasions, embedding the address between <> is not necessary, just insert the URL in the document and the application will automatically convert it.

The rendered output looks like this:

Disabling automatic URL linking

The rendered output looks like this:

NOTE: It is worth remembering that the use of backticks to surround content transforms it into code.

Markdown code block

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ‘ AT&T ‘. You even need to escape ampersands within URLs. Thus, if you want to link to:

you need to encode the URL as:

in your anchor tag href attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

So, if you want to include a copyright symbol in your article, you can write:

and Markdown will leave it alone. But if you write:

Markdown will translate it to:

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

Markdown will translate it to:

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single and & in your example code needs to be escaped.)

The implication of the «one or more consecutive lines of text» rule is that Markdown supports «hard-wrapped» text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s «Convert Line Breaks» option) which translate every line break character in a paragraph into a
tag.

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Alternatively, a line ending with a backslash \ that’s at the very end of the line (that’s not inside a table or code block) will also translate into a
tag (the \ is replaced). To keep a literal \ at the end of a line (that’s not inside a table or code block), double it.

If you end a line with three or more spaces then a
tag will be generated instead of the plain
tag.

Markdown supports two styles of headers, [Setext] 1 and [atx] 2.

Setext-style headers are «underlined» using equal signs (for first-level headers), dashes (for second-level headers) and tildes (for third-level headers). For example:

‘s, try to use at least four to avoid being mistaken for strike through text or a

-delimited code block.

An optional matching «overline» may precede the header like so:

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

Markdown uses email-style > characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of > :

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

Markdown supports ordered (numbered, lettered or roman numeraled) and unordered (bulleted) lists.

is equivalent to:

Ordered lists use numbers or letters (latin or greek) or roman numerals followed by a period or right parenthesis ) :

It’s important to note that the actual numbers (or letters or roman numerals) you use to mark the list do have an effect on the HTML output Markdown produces, but only if you skip ahead and/or change the list marker style.

The HTML Markdown produces from the above list is:

If you instead wrote the list in Markdown like this:

The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

However, if later list items change the style, an attempt is made to modify the list numbering style for that item which should be effective in just about any browser available today.

Similarly if a list item «skips ahead» an attempt is made to skip the list number ahead which again should be effective in just about any browser available today.

will end up being displayed like this without the [style sheet]:

If you do use lazy list numbering, however, you should still start the list with the number 1 (or letter A or a or roman numeral I or i) or even a higher number if desired and then stick with that number (or letter) for the rest of the items. Since you may only skip forward in the numbering, the items will end up numbered (or «lettered») starting with the value used for the first item.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces.

Attempts to change an unordered list’s style or switch from an ordered list to an unordered list (or vice versa) in mid-list are ignored.

Lists end when the first non-blank, non-indented line (relative to the current list nesting level) is encountered that does not begin with a list marker.

To create two distinct lists when there are only blank lines between the end of the first list and the start of the second, a separator line must be inserted. ([Horizontal rules] work just fine for this).

If desired, an XML-style comment (e.g. ) may be used for this purpose provided it is preceded and followed by at least one blank line.

Any non-list-marker, non-blank, non-indented (relative to the current list nesting level) line may be used for this purpose but the XML-style comment has the advantage of not causing anything extra to be shown when the HTML output is displayed in a browser.

To make lists look nice, you can wrap items with hanging indents:

But if you want to be lazy, you don’t have to:

If list items are separated by blank lines, Markdown will wrap the items in

tags in the HTML output. For example, this input:

radiovisual/markdown-for-everyone

Use Git or checkout with SVN using the web URL.

Work fast with our official CLI. Learn more.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio Code

Your codespace will open once ready.

There was a problem preparing your codespace, please try again.

Latest commit

Git stats

Files

Failed to load latest commit information.

readme.md

Markdown For Everyone

Markdown is an incredibly simple and hassle-free alternative to HTML. Markdown accomplishes the same thing as HTML, but Markdown uses a simple, easy-to-learn syntax that allows you to add a variety of styling options to your plain-text without all the hassle of opening and closing tags.

Use this cheatsheet as a way of demonstrating specific Markdown features. Because this document was written using Markdown, you can alternatively view this file’s raw plaintext to see more of the specific markdown formatting used in this document.

Note: Markdown used on Github resources differs slightly in its feature set then Markdown used elsewhere, but once you learn the basics of Github-flavored Markdown, you are ready to write Markdown everywhere.

Table of Contents

Headings from h1 through h6 are constructed with a # for each level:

Markdown Syntax

Mark Gruber’s Markdown syntax.

This documentation lays out the syntax of Mark Gruber’s Markdown specifications. It is taken from his site. The content and info is his words, but it is here for convenience.

Overview

Philosophy

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. 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. While Markdown’s syntax has been influenced by several existing text-to-HTML filters – including Setext, atx, Textile, reStructuredText,
Grutatext, and EtText – the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

Inline HTML

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

The only restrictions are that block-level HTML elements – e.g.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Automatic Escaping for Special Characters

Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ‘ AT&T ‘. You even need to escape ampersands within URLs. Thus, if you want to link to:

you need to encode the URL as:

in your anchor tag href attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

So, if you want to include a copyright symbol in your article, you can write:

and Markdown will leave it alone. But if you write:

Markdown will translate it to:

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

Markdown will translate it to:

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single and & in your example code needs to be escaped.)

Block Elements

Paragraphs and Line Breaks

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line – a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

The implication of the “one or more consecutive lines of text” rule is that Markdown supports “hard-wrapped” text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s “Convert Line Breaks” option) which translate every line break character in a paragraph into a
tag.

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Yes, this takes a tad more effort to create a
, but a simplistic “every line break is a
” rule wouldn’t work for Markdown. Markdown’s email-style blockquoting and multi-paragraph list items work best – and look better – when you format them with hard breaks.

Headers

Markdown supports two styles of headers, Setext and atx.

Setext-style headers are “underlined” using equal signs (for first-level headers) and dashes (for second-level headers). For example:

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

Optionally, you may “close” atx-style headers. This is purely cosmetic – you can use this if you think it looks better. The closing hashes don’t even need to match the number of hashes used to open the header. (The number of opening hashes determines the header level.) :

Blockquotes

Markdown uses email-style > characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of > :

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

Lists

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use asterisks, pluses, and hyphens – interchangably
– as list markers:

is equivalent to:

Ordered lists use numbers followed by periods:

It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

If you instead wrote the list in Markdown like this:

you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

But if you want to be lazy, you don’t have to:

If list items are separated by blank lines, Markdown will wrap the
items in

tags in the HTML output. For example, this input:

Markdown code block

Note: This document is itself written using Markdown; you can see the source for it by adding ‘.text’ to the URL.

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Automatic Escaping for Special Characters

Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ‘ AT&T ‘. You even need to escape ampersands within URLs. Thus, if you want to link to:

you need to encode the URL as:

in your anchor tag href attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

So, if you want to include a copyright symbol in your article, you can write:

and Markdown will leave it alone. But if you write:

Markdown will translate it to:

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

Markdown will translate it to:

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single and & in your example code needs to be escaped.)

Paragraphs and Line Breaks

The implication of the «one or more consecutive lines of text» rule is that Markdown supports «hard-wrapped» text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s «Convert Line Breaks» option) which translate every line break character in a paragraph into a
tag.

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Markdown supports two styles of headers, [Setext] 1 and [atx] 2.

Setext-style headers are «underlined» using equal signs (for first-level headers) and dashes (for second-level headers). For example:

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

Markdown uses email-style > characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of > :

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

Markdown supports ordered (numbered) and unordered (bulleted) lists.

is equivalent to:

Ordered lists use numbers followed by periods:

It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

If you instead wrote the list in Markdown like this:

you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

But if you want to be lazy, you don’t have to:

If list items are separated by blank lines, Markdown will wrap the items in

tags in the HTML output. For example, this input:

Markdown code block

Note: This document is itself written using Markdown; you can see the source for it by adding ‘.text’ to the URL.

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Automatic Escaping for Special Characters

Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ‘ AT&T ‘. You even need to escape ampersands within URLs. Thus, if you want to link to:

you need to encode the URL as:

in your anchor tag href attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.

So, if you want to include a copyright symbol in your article, you can write:

and Markdown will leave it alone. But if you write:

Markdown will translate it to:

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

Markdown will translate it to:

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single and & in your example code needs to be escaped.)

Paragraphs and Line Breaks

The implication of the «one or more consecutive lines of text» rule is that Markdown supports «hard-wrapped» text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s «Convert Line Breaks» option) which translate every line break character in a paragraph into a
tag.

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Markdown supports two styles of headers, [Setext] 1 and [atx] 2.

Setext-style headers are «underlined» using equal signs (for first-level headers) and dashes (for second-level headers). For example:

Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:

Markdown uses email-style > characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of > :

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.

Markdown supports ordered (numbered) and unordered (bulleted) lists.

is equivalent to:

Ordered lists use numbers followed by periods:

It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

If you instead wrote the list in Markdown like this:

you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

But if you want to be lazy, you don’t have to:

If list items are separated by blank lines, Markdown will wrap the items in

tags in the HTML output. For example, this input:

Last Modified: May 23, 2021

In this comprehensive guide, we’ll learn Markdown syntax with examples.

Overview

Markdown is a lightweight markup language that is used to format and style the content of text document. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.

You write markdown in plain text format, which is easier to read and write for most humans, and then Markdown processor convert the plain text into HTML.

There are many markdown processors available. Markdown syntax and support for elements may slightly differ depending upon which markdown processor is being used.

Let’s learn how to format text using various Markdown syntax with examples:-

Block Elements

Headings

Hash # is used to create headings. The number of hashes denotes the heading level for e.g. ### denotes the third level heading.

Heading 1

Heading 1

Heading 1

Heading 2

Heading 3

Heading 3

Heading 4

Heading 4

Heading 5

Heading 5

Heading 6

Heading 6

✅ Always add space between # and the heading for e.g. # Heading 1 works but #Heading 1 doesn’t.
✅ Headings are supported by all Markdown processors.

Alternate syntax for h1 and h2

Heading 1

Heading 1

Heading 1

Heading 1

Heading 1

Heading 2

Heading 1

Heading 2

Paragraphs

Single Paragraph

A simple line of text in Markdown creates a paragraph.

This is a paragraph

This is a paragraph

Multiple Paragraphs

A blank line is used to separate paragraphs.

I love Markdown.

It’s easier to read and write as compare to HTML.

If a blank line is not used then it is considered as a single paragraph even if the text is in multiple lines.

I love Markdown. It’s easier to read and write as compare to HTML.

Paragraph with line break

To add a line break in a paragraph, end a line with two or more spaces.

I love Markdown.
It’s easier to read and write as compare to HTML.

Note: » › » denotes the space in above example.

❌ Do not indent the paragraph with spaces or tabs. It may render different output by different Markdown processors.
✅ Always keep paragraph left-aligned.
✅ Paragraphs are supported by all Markdown processors.

Ordered List

💡 The numbers don’t have to be in numerical order, but the list should start with the number one i.e. 1.

Nested Ordered List

Nested list items can be created by adding indentation to the line. Each indentation creates a deeper nested level.

❌ You can also use parenthesis 1) instead of period 1. but not recommended, because few markdown processor support this.
✅ Ordered lists are supported by all Markdown processors.

Unordered List

Nested Unordered List

Nested list items can be created by adding indentation to the line. Each indentation creates deeper nested level.

Escape period in ordered and unordered list

Escape dash, asterisk and plus in ordered and unordered list

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.

❌ Definition lists are NOT supported by all Markdown processors.

Blockquotes

Blockquotes with single paragraph

Blockquotes is created by adding greater sign > in front of a text.

Blockquotes with multiple paragraphs

Blockquotes can contain multiple paragraphs. Add a greater sign > on the blank lines as well between the paragraphs.

This is a blockquote with two paragraphs. I am first paragraph.

I am second paragraph.

Nested Blockquotes

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional > for each nested level.

Back to the first level.

Back to the first level

Formatted Blockquotes

Blockquotes can be formatted with other elements such as headers, lists, emphasis and code blocks. Not all the elements works though, try them and see yourself.

This is a header

some example code :

✅ Blockquotes are supported by all Markdown processors.

Code Blocks

Code blocks are used to write programming code snippet. You can create a code block by indenting every line of the block by at least 4 spaces or 1 tab

Note: » › » denotes the space in above example.

Fenced Code Blocks

If you find adding 4 spaces or one tab on each line of the block is more inconvenient then some markdown processors also support three backticks «` or three tildes

before and after the code block.

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 three backticks for e.g. «`javascript

Note that syntax highlighting support for a language and how the syntax are displayed for that language varies across different Markdown processors. You can try from this full list of languages, if that works for you:-

✅ Code block (without Syntax highlighting) is supported by all Markdown processors.
❌ Code blocks with Syntax highlighting is NOT supported by all Markdown processors.

Horizontal Rules

produce a horizontal rule like below:-

✅ Horizontal rules are supported by all Markdown processors.

Tables

You can optionally add pipes on either end of the table.

Table Column Text 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.

Table Cell Text Formatting

You can format the text within table cells. For example, you can add links, code (not code blocks), and emphasis. You can’t add headings, blockquotes, lists, horizontal rules, images, or HTML tags.

Escape Pipe in Tables

If you want to use | character as a text in the table then you can escape it with blackslash i.e. \|

❌ Tables are NOT supported by all Markdown processors.

Task Lists

Task 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.

❌ Task lists are NOT supported by all Markdown processors.

Span Elements

Emphasis

Add two asterisks ** or two underscores __ before and after a word for e.g. **bold** or __bold__ to render as bold.

You can only use asterisks ** and not underscores __ to make part of the word bold. Using __ in part of the word considered as underscore _ and not syntax.

Italic

Add an asterisk * or underscore _ before and after a word for e.g. *italic* or _italic_ to render as italic.

You can only use asterisk * and not underscores _ to make part of the word italic. Using _ in part of the word considered as underscore _ and not syntax.

✅ Italic is supported by all Markdown processors.

Strikethrough

before and after a word for e.g.

strike and through

Inline Link

Inline Link with Title

Inline Link can also be created with optional title which is displayed when hover on the link.

Inline Link with URL and Email Address

URL or email address can quickly be turned into a clickable link by wrapping it in angle brackets <>

Automatic URL and Email Address Link

💡 Many markdown processors (but not all) automatically turns URL and Email Address into clickable link even without wrapping in <>

Reference Links

Reference-style links are constructed in two parts: first part is link text which you keep inline and the second part is URL which you define somewhere else in the document.

I get 10 times more traffic from Google than from Yahoo or MSN.

Image

Inline Image

Inline Image with Title

Inline Image with Link

Clickable image can also be created with link URL for e.g. [](URL)

Reference Image

Reference-style images are constructed in two parts: first part is alt text which you keep inline and the second part is image patg which you define somewhere else in the document.

✅ Images are supported by all Markdown processors.

Escape backticks in code

Escaping Characters

Sometime we want to display the characters in literal way which are used as a Markdown syntax. In such cases, add a backslash \ in front of the character.

You can escape the following characters in Markdown:-

Summary

Congratulations! We have learned all the syntax supported by most of the Markdown processors.

You can further read following useful resources:-

jonschlinkert / markdown-cheatsheet.md

(Also see remarkable, the markdown parser created by the author of this cheatsheet)

Table of contents

The following markdown features are defined by the CommonMark standard, and are generally supported by all markdown parsers and editors.

Headings from h1 through h6 are constructed with a # for each level:

Renders to this HTML:

Which looks like this in the browser:

A note about «Setext» Headings

Note that this document only describes ATX headings, as it is the preferred syntax for writing headings. However, the CommonMark specification also describes Setext headings, a heading format that is denoted by a line of dashes or equal signes following the heading. It’s recommended by the author of this guide that you use only ATX headings, as they are easier to write and read in text editors, and are less likeley to conflict with other syntaxes and demarcations from language extensions.

Body copy written as normal plain-text will be wrapped with

tags in the rendered HTML.

Renders to this HTML:

You can use multiple consecutive newline characters ( \n ) to create extra spacing between sections in a markdown document. However, if you need to ensure that extra newlines are not collapsed, you can use as many HTML
elements as you want.

The HTML element is for creating a «thematic break» between paragraph-level elements. In markdown, you can use of the following for this purpose:

For emphasizing a snippet of text with a heavier font-weight.

The following snippet of text is rendered as bold text.

rendered as bold text

For emphasizing a snippet of text with italics.

The following snippet of text is rendered as italicized text.

rendered as italicized text

Used for defining a section of quoting text from another source, within your document.

To create a blockquote, use > before any text you want to quote.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

And the generated HTML from a markdown parser might look something like this:

Blockquotes can also be nested:

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.

Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.

A list of items in which the order of the items does not explicitly matter.

You may use any of the following symbols to denote bullets for each list item:

A list of items in which the order of items does explicitly matter.

Sometimes lists change, and when they do it’s a pain to re-order all of the numbers. Markdown solves this problem by allowing you to simply use 1. before each item in the list.

Automatically re-numbers the items and renders to:

For example, to show

«Fenced» code block

For example, this:

Renders to something like this in HTML:

And appears like this when viewed in a browser:

You may also indent several lines of code by at least four spaces, but this is not recommended as it is harder to read, harder to maintain, and doesn’t support syntax highlighting.

Which renders to:

And this complicated HTML is an example of what might be generated by the markdown parser, when syntax highlighting is applied by a library like highlight.js:

URIs or email addresses that are not wrapped in angle brackets are not recognized as valid autolinks by markdown parsers.

Renders to (hover over the link, there is no tooltip):

Renders to (hover over the link, there should be a tooltip):

Named anchors enable you to jump to the specified anchor point on the same page.

For example, the following «chapter» links:

. will jump to these sections:

Anchor placement

Note that placement of achors is arbitrary, you can put them anywhere you want, not just in headings. This makes adding cross-references easy when writing markdown.

Images have a similar syntax to links but include a preceding exclamation point.

Like links, Images also have a footnote style syntax

With a reference later in the document defining the URL location:

Any text between and > that looks like an HTML tag will be parsed as a raw HTML tag and rendered to HTML without escaping.

(Note that markdown parsers do not attempt to validate your HTML).

Escaping with backslashes

Any ASCII punctuation character may be escaped using a single backslash.

*this is not italic*

The following markdown features are not defined by the CommonMark specification, but they are commonly supported by markdown parsers and editors, as well as sites like GitHub and GitLab.

In GitHub Flavored Markdown (GFM) you can do strickthroughs.

Which renders to:

Strike through this text.

Links in todo lists

Tables are created by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header (this line of dashes is required).

Center text in a column

To center the text in a column, add a colon to the middle of the dashes in the row beneath the header.

Right-align the text in a column

To right-align the text in a column, add a colon to the middle of the dashes in the row beneath the header.

Markdown footnotes are not officially suppored by the CommonMark specification. However, the feature is supported by remarkable and other markdown parsers, and it’s very useful when available.

The accompanying text for the footnote can be added elsewhere in the document using the following syntax:

When rendered to HTML, footnotes are «stacked» by the markdown parser at the bottom of the file, in the order in which the footnotes were defined.

What is markdown?

Sites like GitHub and Stackoverflow have popularized the use markdown as a plain-text alternative to traditional text editors, for writing things like documentation and comments.

All contributions are welcome!

Please let me know if you find typos, grammar or spelling mistakes, or have a suggestion for improving the cheatsheet (since GitHub does not send notifications for gists, it might be better to contact me on twitter, at @jonschlinkert).

How to include code in docs

There are several ways other than screenshots to include code in an article published on docs.microsoft.com:

Individual elements (words) within a line.

Here’s an example of code style.

Use code format when referring to named parameters and variables in a nearby code block in your text. Code format may also be used for properties, methods, classes, and language keywords. For more information, see Code elements later in this article..

Code blocks in the article Markdown file.

Use inline code blocks when it’s impractical to display code by reference to a code file. For more information, see Code blocks later in this article.

Code blocks by reference to a code file in the local repository.

For more information, see In-repo snippet references later in this article.

Code blocks by reference to a code file in another repository.

For more information, see Out-of-repo snippet references later in this article.

Code blocks that let the user execute code in the browser.

For more information, see Interactive code snippets later in this article.

Besides explaining the Markdown for each of these ways to include code, the article provides some general guidance for all code blocks.

Code elements

A «code element» is a programming language keyword, class name, property name, and so forth. It’s not always obvious what qualifies as code. For example, NuGet package names should be treated as code. When in doubt, see Text formatting guidelines.

Inline code style

To include a code element in article text, surround it with backticks (`) to indicate code style. Inline code style shouldn’t use the triple-backtick format.

When an article is localized (translated into other languages), text styled as code is left untranslated. If you want to prevent localization without using code style, see Non-localized strings.

Bold style

Some older style guides specify bold for inline code. Bold is an option when code style is so obtrusive as to compromise readability. For example, a Markdown table with mostly code elements might look too busy with code styling everywhere. If you choose to use bold style, use non-localized strings syntax to make sure that code is not localized.

Links

A link to reference documentation may be more helpful than code format in some contexts. If you use a link, don’t apply code format to the link text. Styling a link as code can obscure the fact that the text is a link.

If you use a link and refer to the same element later in the same context, make the subsequent instances code format rather than links. For example:

The first reference to System.CommandLine in this text is a link. Subsequent references to System.CommandLine can be in code style.

Placeholders

If you want the user to replace a section of displayed code with their own values, use placeholder text marked off by angle brackets. For example:

You may note that the brackets must be removed when substituting real values. The Microsoft Writing Style Guide calls for italics, which you may format within angle bracketed inline code:

Curly braces < >are discouraged for use as syntactical placeholders. They may be confused with the same notation used in replaceable text, format strings, string interpolation, text templates, and similar programming constructs.

Placeholder names can be separated by hyphens («kebab case»), with underscores, or not separated at all (Pascal case). Kebab case may generate syntax errors and underscores may conflict with underlining. All-caps may conflict with named constants in many languages, though it may also draw attention to the placeholder name.

Code blocks

The syntax for including code in a doc depends on where the code is located:

Following are guidelines that apply to all three types of code blocks:

Screenshots

All of the methods listed in the preceding section result in usable code blocks:

These are just a few of the reasons why IDE screenshots aren’t recommended as a method of including code in an article. Use IDE screenshots for code only if you’re showing something about the IDE itself, like IntelliSense. Don’t use screenshots just to show colorization and highlighting.

Code validation

If you are including code blocks from another repository, work with the owners on a maintenance strategy for the code so that your included code does not break or go out of date as new versions of the libraries the code uses are shipped.

Highlighting

Snippets typically include more code than necessary in order to provide context. It helps readability when you highlight the key lines that you’re focusing on in the snippet, as in this example:

You can’t highlight code when you include it in the article Markdown file. It works only for code snippets included by reference to a code file.

Horizontal scroll bars

Break up long lines to avoid horizontal scroll bars. Scroll bars on code blocks make code hard to read. They’re especially problematic on longer code blocks, where it may be impossible to see the scroll bar and the line you want to read at the same time.

A good practice for minimizing horizontal scroll bars on code blocks is to break up code lines longer than 85 characters. But keep in mind that the presence or absence of a scroll bar isn’t the only criterion of readability. If breaking a line before 85 hurts readability or copy-paste convenience, feel free to go over 85.

Clearly identify bad code

In some scenarios, it’s helpful to point out coding patterns that should be avoided, for example:

For these scenarios:

Explain the error both in code comments and article text.

Readers often skip article text and look only at code, so it’s not enough to explain the error only in article text. It’s also not enough to explain the error only in code comments, because code comments aren’t localized.

Consider commenting out the code if it would cause a compiler error.

Commented-out code won’t disrupt the continuous integration (CI) system if the article’s repo has one now or implements one in the future.

Inline code blocks

Use inline code blocks only when it’s impractical to display code by reference to a code file. Inline code is generally more difficult to test and keep up to date compared to a code file that is part of a complete project. And inline code may omit context that could help the developer to understand and use the code. These considerations apply mainly to programming languages. Inline code blocks can also be used for outputs and inputs (such as JSON), query languages (such as SQL), and scripting languages (such as PowerShell).

There are two ways to indicate a section of text in an article file is a code block: by fencing it in triple-backticks («`) or by indenting it. Fencing is preferred because it lets you specify the language. Avoid using indentation because it’s too easy to get wrong and it may be hard for another writer to understand your intent when they need to edit your article.

Language indicators are placed immediately after the opening triple-backticks, as in the following example:

GitHub Flavored Markdown supports delimiting code blocks with tildes (

) as well as with backticks (`). The symbol used to open and close the code block must be consistent within the same code block.

For information about the values you can use as language indicators, see Language names and aliases.

If you use a language or environment word after the triple-backticks («`) that isn’t supported, that word appears in the code section title bar on the rendered page. Whenever possible, use a language or environment indicator in your inline code blocks.

If you copy and paste code from a Word document, make sure it has no «curly quotes,» which aren’t valid in code. If it does, change them back to normal quotes ( ‘ and » ). Alternatively, rely on the Docs Authoring Pack, smart quotes replacement feature.

In-repo snippet references

The preferred way to include code snippets for programming languages in docs is by reference to a code file. This method gives you the ability to highlight lines of code and makes the wider context of the snippet available on GitHub for developers to use. You can include code by using the triple colon format (. ) either manually or in Visual Studio Code with the help of the docs.microsoft.com Authoring Pack.

Display entire code file:

Display part of a code file by specifying line numbers:

Display part of a code file by specifying a snippet name:

The following sections explain these examples:

For more information, see Snippet syntax reference later in this article.

Path to code file

The example is from the ASP.NET docs repo, aspnetcore/data/ef-mvc/crud.md article file. The code file is referenced by a relative path to aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs in the same repository.

Selected line numbers

This example displays only lines 2-24 and 26 of the StudentController.cs code file.

Prefer named snippets over hard-coded line numbers, as explained in the next section.

Named snippet

Use only letters and underscores for the name.

The example displays the snippet_Create section of the code file. The code file for this example has snippet tags in comments in the C# code:

Named code snippets can be nested, as shown in the following example:

When the Method code snippet is rendered, the Line tags aren’t included in the rendered output.

Whenever you can, refer to a named section rather than specifying line numbers. Line number references are brittle because code files inevitably change in ways that make line numbers change. You don’t necessarily get notified of such changes. Your article eventually starts showing the wrong lines and you have no clue anything has changed.

Highlighting selected lines

The example highlights lines 2 and 5, counting from the start of the displayed snippet. Line numbers to highlight don’t count from the start of the code file. In other words, lines 3 and 6 of the code file are highlighted.

Out-of-repo snippet references

If the code file you want to reference is in a different repository, set up the code repository as a dependent repository. When you do that, you specify a name for it. That name then acts like a folder name for purposes of code references.

For example, the docs repository is Azure/azure-docs, and the code repository is Azure/azure-functions-durable-extension.

In the root folder of azure-docs, add the following section in .openpublishing.publish.config.json:

Now when you refer to samples-durable-functions as if it were a folder in azure-docs, you’re actually referring to the root folder in the azure-functions-durable-extension repository.

You can include code by using the triple colon format (. ) either manually or in Visual Studio Code with the help of the docs.microsoft.com Authoring Pack.

Your snippet reference will look like this:

In the azure-functions-durable-extension repository, that code file is in the samples/csx/shared folder. As noted earlier, line numbers for highlighting are relative to the start of the snippet rather than the start of the file.

The name you assign to the dependent repository is relative to the root of the main repository, but the tilde (

/../samples-durable-functions instead of

Snippets in a Jupyter notebook

You can reference a cell in a Jupyter notebook as a code snippet. In order to reference the cell:

Add metadata to notebook

Name the cell by adding cell metadata in the Jupyter notebook.

In the cell metadata, add a «name» attribute:

You can add any other metadata you’d like to help you track where the cell is being used. For example:

Set up repository access

If the notebook file you want to reference is in a different repository, set up the code repository as a dependent repository.

Jupyter notebook snippet syntax reference

Once your notebook contains the required metadata, reference it in your markdown file. Use the you added to the notebook, and the

you set up as your dependent repository.

This syntax is a block Markdown extension. It must be used on its own line.

Use any of the supported languages for the identifier.

Interactive code snippets

Inline interactive code blocks

For the following languages, code snippets can be made executable in the browser window:

When interactive mode is enabled, the rendered code boxes have a Try It or Run button. For example:

renders as follows:

To turn on this feature for a particular code block, use a special language identifier. The available options are:

For the Azure Cloud Shell and PowerShell Cloud Shell, users can run commands against only their own Azure account.

Code snippets included by reference

You can enable interactive mode for code snippets included by reference. To turn on this feature for a particular code block, use the interactive attribute. The available attribute values are:

Here are some examples:

For the Azure Cloud Shell and PowerShell Cloud Shell, users can only run commands against their own Azure account.

Snippet syntax reference

This syntax is a block Markdown extension. It must be used on its own line.

Supported languages

The Docs Authoring Pack includes a feature to provide statement completion and validation of the available language identifiers for code fence blocks.

Fenced code blocks

The Docs Authoring Pack, Dev Lang Completion feature uses the first valid alias when multiple aliases are available.

Next steps

For information on text formatting for content types other than code, see Text formatting guidelines.

Bitbucket Support

Knowledge base

Products

Jira Software

Project and issue tracking

Jira Service Management

Service management and customer support

Jira Core

Manage any business project

Confluence

Bitbucket

Git code management

Resources

Documentation

Usage and admin help

Community

Answers, support, and inspiration

Suggestions and bugs

Feature suggestions and bug reports

Marketplace

Billing and licensing

Frequently asked questions

Viewport

Confluence

Versions

Markdown syntax guide

Use Bitbucket Data Center and Server

On this page

Related content

Still need help?

The Atlassian Community is here for you.

Bitbucket Data Center and Server uses Markdown for formatting text, as specified in CommonMark (with a few extensions). You can use Markdown in the following places:

Use Control-Shift-P or Command-Shift-P to preview your markdown.

Markdown syntax

The page below contains examples of Markdown syntax. For a full list of all the Markdown syntax, consult the CommonMark help or specification.

On this page:

Headings

Paragraphs

Paragraphs are separated by empty lines. To create a new paragraph, press twice.

Character styles

Unordered list

Ordered list

List in list

Quotes or citations

Inline code characters

Code blocks

Bitbucket uses CodeMirror to apply syntax highlighting to the rendered markdown in comments, READMEs and pull request descriptions. All the common coding languages are supported, including C, C++, Java, Scala, Python and JavaScript. See Configuring syntax highlighting for file extensions.

Within a code block, ampersands (&) and angle brackets ( ) are automatically converted into HTML entities.

Links to external websites

Linking issue keys to JIRA applications

When you use Jira application issue keys (of the default format) in comments and pull request descriptions Bitbucket automatically links them to the Jira application instance.

The default Jira application issue key format is two or more uppercase letters ( [A-Z][A-Z]+ ), followed by a hyphen and the issue number, for example TEST-123.

Linking to pull requests

Introduced with Bitbucket 4.9, you can reference pull requests from comments and descriptions in other pull requests. The syntax for linking to pull request looks like this:

To link to a pull request in the same project and repository, you only need to include the pull request ID.

To link to a pull request in the same project but a different repository, include the repository slug before the pull request ID.

To link to a pull request in a different project and repository, include the project key and the repository slug before the pull request ID.

Images

Inline image syntax looks like this:

Reference image links look like this:

Where ‘id’ is the name of a previously defined image reference, using syntax similar to link references:

An example using reference image links:

You can specify image height and width as key=value pairs inside curly braces < >after the applicable image node. For example:

Tables

Backslash escapes

Certain characters can be escaped with a preceding backslash to preserve the literal display of a character instead of its special Markdown meaning. This applies to the following characters:

\ backslash
` backtick
* asterisk
_ underscore
<> curly braces
[] square brackets
() parentheses
# hash mark
> greater than
+ plus sign
— minus sign (hyphen)
. dot
! exclamation mark

Markdown Basic Syntax

In this article you will learn about the elements that form the basis of the Markdown language.

Overview

Despite some variations, most applications support the basic elements of Markdown. These elements are essential for you to be able to format a document. But make no mistake, using only the basics of Markdown you can create well-designed sites for Web.

NOTE: Whenever possible, when there are syntax variations from one Markdown processor to another, these will be noted in the article.

Titles

Every document has or should have a title, correct? So, let’s start with it.

The symbol used to format a title in Markdown is the hash # one. When building the title, format the code by placing a hash at the beginning of the line, demarcating the header.

It will be converted to HTML’s h1 tag.

photo Title H1 in Markdown converted to HTML

NOTE: the h1 tag represents the most important title of the HTML, usually the title of the article.

The number of hashes that you use at the beginning of the line indicates the level of the title, therefore, the formatting ### My title creates a level 3 heading.

photo Markdown Titles on StackEdit

Alternative syntax

photo Alternative syntax for creating level 1 and level 2 headings

photo Alternative syntax for headings using only one sign

Titles: best practices

You may encounter compatibility issues when we talk about the space between the hash sign # at the beginning of the line and the title text.

It is always recommended to add at least one space between them, in addition to providing a better reading of your document, you will still have more editing support among the Markdown applications.

Table 1.3 exemplifies the correct construction of the title.

photo Building a title in Markdown the right way

Paragraphs

The simplest formatting in Markdown is the paragraph. To create one, simply separate a piece of text with a blank line, creating fragmentations that the Markdown processor will interpret as paragraphs.

photo Paragraphs in Markdown

Markdown is important for every programmer.

Learning Markdown is essential for a successful career.

Paragraphs: best practices

Usually the paragraph is stuck at the beginning of the line, that is, avoid indenting it using spaces of any kind, neither blanks nor tabs.

NOTE: The paragraph must be indented when it is within a list.

Table 1.5 exemplifies the correct use of Markdown formatting for constructing a paragraph.

Not recommended