This document demonstrates Markdown features, and shows how they look using my Jekyll style.

It is based on the official syntax description, but I removed or shortened many examples and included them in the code to show how they render.

Note that Jekyll supports some extensions beyond the basic Markdown syntax as described here.

Markdown: Syntax

Overview
Block Elements
Span Elements
- Links
- Emphasis
- Code
- Images
Miscellaneous

Overview

Philosophy

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.

Inline HTML

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web. For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.

Block-level HTML elements – e.g. <div>, <table>, <pre>, <p>, etc. – must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

For example, to add an HTML table to a Markdown article:

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

yields:

This is a regular paragraph.

Foo

This is another regular paragraph.

Span-level HTML tags – e.g. <span>, <cite>, or <del> – can be used anywhere in a Markdown paragraph, list item, or header. Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Automatic Escaping for Special Characters

In HTML, there are two characters that demand special treatment: < and &. Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you must escape them as entities, e.g. <, and &.

If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into &.

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 AT&T Markdown will translate it to: AT&T.

If you write 4 < 5 Markdown will translate it to 4 < 5.

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.

Block Elements

Paragraphs and Line Breaks

The implication of the “one or more consecutive lines of text” rule is that Markdown supports “hard-wrapped” text paragraphs. When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return: Like this
And here the paragraph goes on.

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:

This is an H1
=============

This is an H2
-------------

Any number of underlining =’s or -’s will work.

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

# This is an H1

## This is an H2

###### This is an H6

Optionally, you may “close” atx-style headers. This is purely cosmetic – you can use this if you think it looks better.

Blockquotes

Markdown uses email-style > characters for blockquoting.

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

yields:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

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

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Blockquotes can be nested:

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

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

> ## This is a header.
>
> 1.   This is the first list item.
> 2.   This is the second list item.
>
> Here's some example code:
>
>     return shell_exec("echo $input | $markdown_script");

This is a header.

This is the first list item.

This is the second list item.

Here’s some example code:
return shell_exec("echo $input | $markdown_script");

Lists

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

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

*   Red
*   Green
*   Blue

yields

Red
Green
Blue

Ordered lists use numbers followed by periods:

Bird
McHale
Parish

yields

Bird
McHale
Parish

You should 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 must be followed by one or more spaces or a tab. If you want to be lazy, you can omit hanging indents:

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

If list items are separated by blank lines, Markdown will wrap the items in <p> tags in the HTML output. For example, this input:

*   Bird

*   Magic

will turn into:

<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>

Bird
Magic

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

1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

This is a list item with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

To put a code block within a list item, the code block needs to be indented twice – 8 spaces or two tabs:

A list item with a code block:
```
<code goes here>
```

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

1986. What a great season.

What a great season.

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

1986\. What a great season.

1986. What a great season.

Code Blocks

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. Markdown wraps a code block in both <pre> and <code> tags.

	This is a code block indented by 2 tabs.

while

This is only indented by 1 tab.

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

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

Horizontal Rules

You can produce a horizontal rule tag (<hr />) 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:

* * *

***

*****

- - -

---------------------------------------

Span Elements

Links

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:

This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.

This is an example inline link. This link has no title attribute.

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link. You define your link label like this, on a line by itself:

This is [an example][id] reference-style link.
This is [an example] [id] reference-style link.

[id]: http://example.com/  "Optional Title Here"

This is an example reference-style link. This is an example reference-style link.

Empty [] copy the id from the text:

Visit [Daring Fireball][] for more information.

[Daring Fireball]: http://daringfireball.net/

Visit Daring Fireball for more information.

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.

Emphasis

There is single and double emphasis, rendered using <em> and <strong>:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

yields:

single asterisks

single underscores

double asterisks

double underscores

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: * _, anywhere else it needs to be es*caped. \*.

Code

To indicate a span of code, wrap it with backtick quotes (`). To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

Images

Inline image syntax looks like this:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

Reference-style image syntax looks like this:

![Alt text][id]

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

[id]: url/to/image  "Optional title attribute"

Markdown has no syntax for specifying the dimensions of an image; if this is important, use regular HTML <img> tags.

Miscellaneous

Automatic Links

For URLs, one can write <http://example.com/> to get http://example.com/. Email addresses work similarly, with automatic obfuscation of the link test@mail.com.

Backslash Escapes

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

Expandable Sections

A useful element of (minimal) interaction are collapsable sections. These can be created using the HTML tags <details> and <summary>

<details markdown="1">
<summary>Click to expand</summary>
  Long text shown only when not collapsed.
  You can use *markdown* inside here, including
  all the cool **features** that has:
  
  * itemized lists
  * `backtick code`
  * and what not.
</details>

Here’s how it looks like:

Click to expand

Long text shown only when not collapsed. You can use markdown inside here, including all the cool features that has:

itemized lists
backtick code
and what not.

Markdown Cheatsheet

Markdown: Syntax

Overview

Philosophy

Inline HTML

Automatic Escaping for Special Characters

Block Elements

Paragraphs and Line Breaks

Headers

Blockquotes

This is a header.

Lists

Code Blocks

Horizontal Rules

Span Elements

Links

Emphasis

Code

Images

Miscellaneous

Automatic Links

Backslash Escapes

Expandable Sections