The syntax of Markdown is incredibly simple and intuitive. At the end of this section, we will have learned all the syntax we need to write anything with Markdown.
Markdown documents are created as plain text files, and it's not a requirement to create these files with concrete file extensions to use them. However, in order for editors or applications to make sure that the file they are using is Markdown-formatted, we could use some of the most common file extensions, such as .md
, .mkdn
, or .markdown
.
A paragraph of text is one or more consecutive lines:
A paragraph, divided into two lines.
The preceding code will produce:
<p>A paragraph, divided into two lines.</p>
Paragraphs separated by one or more blank lines create new paragraphs:
A paragraph Another paragraph, separated by a new line.
The preceding code will produce:
<p>A paragraph</p> <p>Another paragraph, separated by a new line.</p>
Two or more spaces at the end of the line create a line break:
A sentence, with a line break.
The preceding code will produce:
<p>A sentence, <br /> with a line break</p>
There are two styles for declaring headers in Markdown: setext and atx.
For the two top-level headers (the <h1>
and <h2>
tags), there is a special syntax that can be used:
Header 1 ======== Header 2 --------
The preceding code will produce:
<h1>Header 1</h1> <h2>Header 2</h2>
Begin a paragraph with a hash (#
), and that paragraph becomes a header. The number of hashes signifies the heading level number (h1
– h6
):
# Header 1 ## Header 2 ### Header 3 #### Header 4 ##### Header 5 ###### Header 6
Optionally, we may close atx hash headers:
# Header 1 # ## Header 2 ## ### Header 3 ### #### Header 4 #### ##### Header 5 ##### ###### Header 6 ######
The preceding code will produce:
<h1>Header 1</h1> <h2>Header 2</h2> <h3>Header 3</h3> <h4>Header 4</h4> <h5>Header 5</h5> <h6>Header 6</h6>
Markdown treats asterisks (*
) and underscores (_
) as indicators of emphasis. A single symbol is used for italics and a double symbol for bold:
*single asterisks* _single underscores_ **double asterisks** __double underscores__
The preceding code will produce:
<em>single asterisks</em> <em>single underscores</em> <strong>double asterisks</strong> <strong>double underscores</strong>
Markdown supports ordered (numbered) and unordered (bulleted) lists.
Ordered lists use numbers as list markers:
1. One 2. Two 6. Six
This will produce:
<ol> <li>One</li> <li>Two</li> <li>Six</li> </ol>
Unordered lists use asterisks (*
), plus signs (+
), and hyphens (-
) as list markers:
* A list. * Second element. + A new entry. - Another entry in a list. - And the list goes on.
The preceding code will produce:
<ul> <li>A list.</li> <li>Second element.</li> <li>A new entry.</li> <li>Another entry in a list.</li> <li>And the list goes on.</li> </ul>
Markdown supports two styles of links: inline and reference. In both styles, the link text is delimited by square brackets ([
and ]
) and the title attribute is optional.
An example is shown as follows:
An example of [inline link](http://example.com "Example"). [This link](http://example.net/) has no title attribute.
The preceding code will produce:
<p>An example of <a href="http://example.com"title="Example">inline link</a>.</p> <p><a href="http://example.net/">This link</a> has no titleattribute.</p>
This is [an example][id] reference-style link. This is [an example] [id] reference-style link.
Then, anywhere in the document, add:
[id]: http://example.com/ "Optional Title Here" [id]: http://example.com/ 'Optional Title Here' [id]: http://example.com/ (Optional Title Here)
This will produce:
<p>This is <a href="http://example.com/" title="Optional TitleHere">an example</a> reference-style link.</p>
Another way to declare a reference link is by using the link text directly:
This is [another example] reference-style link.
Again, we need the link label somewhere in the document:
[another example]: http://example.com/
Creating automatic links is possible by wrapping the text with angle brackets (<
and >
)
The automatic URL as follows:
<http://example.com/>
This will produce:
<p><a href="http://example.com/">http://example.com/</a></p>
An encoded mailto as follows:
This will produce:
<p><a href="mailto:[email protected]">[email protected]</a></p>
The syntax for blockquotes is similar to that of e-mail blockquotes—it uses right-angle brackets (>
):
> A blockquote. > Another line of blockquote.
Optionally, we may only put one bracket before the first line of a paragraph:
> A blockquote. Another line of blockquote.
The preceding code will produce:
<blockquote> <p>A blockquote. Another line of blockquote.</p> </blockquote>
Blockquotes can be nested:
> First level of the quote. >> Nested blockquote.
The preceding code will produce:
<blockquote> <p>First level of the quote.</p> <blockquote> <p>Nested blockquote.</p> </blockquote> </blockquote>
The embedding of pre-formatted code blocks is possible by indenting every line of the block with four spaces or one tab:
echo 'Hello World'
The preceding code will produce:
<pre><code>echo 'Hello World'</code></pre>
To insert inline code, we wrap it with backticks (`
and`
):
Type `echo 'Hello World'` in your terminal
The preceding code will produce:
<p>Type <code>echo 'Hello World'</code> in your terminal</p>
Markdown uses syntax similar to that of the links to insert images in a document, allowing two styles: inline and reference.
![Alt text](/path/to/img.jpg "Optional title")
The preceding code will produce:
<p><img src="/path/to/img.jpg" alt="Alt text" title="Optional title" /></p>
To insert a horizontal separator, put three or more hyphens (-
), asterisks (*
), or underscores (_
) on a line:
--- *** ***** * * * ___
Any of these will produce:
<hr />
Markdown uses many symbols to specify its syntax. If we want to write any of them without being interpreted, Markdown provides backslash escapes () for the following characters:
backslash ` backtick * asterisk _ underscore {} curly braces [] square brackets () parentheses # hash mark + plus sign - minus sign (hyphen) . dot ! exclamation mark
Escape asterisks in text as shown in the following code:
*this text is surrounded by literal asterisks*
This will produce:
<p>*this text is surrounded by literal asterisks*</p>
Finally, Markdown allows you to include raw HTML. You may write HTML code anywhere in a document. Consider the following example:
This is a paragraph. <table> <tr> <td>Row</td> </tr> </table> This is another paragraph.
The preceding code will produce:
<p>This is a paragraph.</p> <table> <tr> <td>Row</td> </tr> </table> <p>This is another paragraph.</p>