` tags in the HTML output. For example, this input:
* Bird
* Magic
will turn into:
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.
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.
Markdown tries to be smart about this and requires either a blank line
before something that looks like a list item or requires that a list
definition is already active or requires that two lines in a row look
like list items in order for Markdown to recognize a list item.
So the above, by itself without the escaped ".", will not start a list
when it's outside of any list unless it's preceded by a blank line or
immediately followed by another line that looks like a list item (either
of the same kind or of a sublist).
~~~~~~
Tables
~~~~~~
Markdown supports simple tables like so:
| Item | Price | Description |
| ---- | -----:| ----------- |
| Nut | $1.29 | Delicious |
| Bean | $0.37 | Fiber |
Output:
Item | Price | Description |
Nut | $1.29 | Delicious |
Bean | $0.37 | Fiber |
The leading `|` on each line is optional unless the first column contains only
zero or more spaces and/or tabs. The trailing `|` on each line is optional
unless the last column contains only zero or more spaces and/or tabs.
At least one `|` must be present in every row of the table.
Leading and trailing whitespace are always trimmed from each column's value
before using it.
To include a literal `|` (vertical bar) character in a column's value, precede
it with a `\` (backslash). To include a literal `\` use `\\` (double them).
The number of columns in the separator row must match exactly the number of
columns in the header row in order for the table to be recognized.
Each separator in the separator line must be one or more `-` (dash) characters
optionally with a `:` (colon) on either or both ends. With no colons the
column alignment will be the default. With a colon only on the left the
alignment will be `left`. With a colon only on the right the alignment will
be `right`. And finally, with a colon on both ends the alignment will be
`center`. The alignment will be applied to the column in both header and body
rows.
If all columns in the header row are empty (i.e. contain only zero or more
spaces and/or tabs), the header row will be omitted from the output. Empty
rows in the body of the table are always preserved in the output.
Body rows that contain fewer columns than the header row have empty columns
added. Body rows that contain more columns than the header row have the
extra columns dropped.
The vertical bars do not need to be lined up, sloppy tables work just fine.
The above example could be rewritten like so:
Item|Price|Description
-|-:|-
Nut|$1.29|Delicious
Bean|$0.37|Fiber
Inline markup is recognized just fine within each column:
|Example
|:-
|~~Strikeout~~ `code` _etc._
Row text can be split over multiple rows by ending a row with a
backslash (`\`) as the last character on the line.
For example, this:
Item|Price|Description
-|-:|-
Nut|$1.29|Delicious
Bean|$0.37|Fiber
Squash|$1.83|Healthy
Generates output something like this:
Item | Price | Description |
Nut | $1.29 | Delicious |
Bean | $0.37 | Fiber |
Squash | $1.83 | Healthy |
But adding a trailing `\` to the end of first table body row like
so:
Item|Price|Description
-|-:|-
Nut|$1.29|Delicious \
Bean|$0.37|Fiber
Squash|$1.83|Healthy
Generates this output instead:
Item | Price | Description |
Nut Bean | $1.29 $0.37 | Delicious Fiber |
Squash | $1.83 | Healthy |
The corresponding columns of the first two rows are merged. It's
possible to merge multiple rows. Adding a trailing `\` to the
second row too would result in a single row output table.
The `\` must be the very last character on the line to be recognized
as a "row-joiner". If the optional trailing `|` has been included
the "row-joiner" must appear after that like so:
Item|Price|Description|
-|-:|-|
Nut|$1.29|Delicious| \
Bean|$0.37|Fiber|
Squash|$1.83|Healthy|
The advantage of including the optional trailing `|` when using a
"row-joiner" is that renderers that do not support the "row-joiner"
will see that as a superfluous extra column instead and discard it.
~~~~~~~~~~~
Style Sheet
~~~~~~~~~~~
If an unordered list item begins with `[ ]` or `[x]` then its bullet will
be suppressed and a nice checkbox shown instead. In order for the fancy
checkboxes to show the markdown style sheet must be included.
It may be included in the output with the `--show-stylesheet` option.
To get just the style sheet, run `Markdown.pl` with no arguments with the
input redirected to `/dev/null`. Without the style sheet these items
will show normally (i.e. with a bullet and as `[ ]` or `[x]`).
Ordered lists that make use of a `)` instead of a `.` to terminate the
marker also require the style sheet otherwise they will display with
the normal `.` marker termination.
~~~~~~~~~~~
Code Blocks
~~~~~~~~~~~
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 `` and `` tags.
To produce a code block in Markdown, simply indent every line of the
block by at least 4 spaces. Alternatively precede the block with a
line consisting of 3 backtick quotes (or more) and follow it with a
line consisting of the same number of backtick quotes -- in this case the
code lines themselves do not require any additional indentation.
For example, given this input:
This is a normal paragraph:
This is a code block.
Or this equivalent input:
This is a normal paragraph.
```
This is a code block.
```
Markdown will generate:
This is a normal paragraph:
This is a code block.
Note that when using the 3 backtick quotes technique, the blank line
before the start of the code block is optional. One level of
indentation -- 4 spaces -- is removed from each line of the code block
unless the 3 backtick quotes are used. For example, this:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
will turn into:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
A code block continues until it reaches a line that is not indented
(or the end of the article) when using the indentation technique or
until a line consisting of the same number of backtick quotes is found
when using the 3 backtick quotes technique.
Note that the 3 backtick quotes (or more) must appear at the beginning
of the line. To include a code block within a list (or other indented
element), the indentation technique must be used.
Also note that within a backticks-delimited code block, tab characters
are always expanded with the tab stop locations 8 characters apart.
Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
are automatically converted into HTML entities. This makes it very
easy to include example HTML source code using Markdown -- just paste
it and indent it, and Markdown will handle the hassle of encoding the
ampersands and angle brackets. For example, this:
will turn into:
<div class="footer">
© 2004 Foo Corporation
</div>
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.
~~~~~~~~~~~~~~~~
Horizontal Rules
~~~~~~~~~~~~~~~~
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:
* * *
***
*****
- - -
---------------------------------------
- - - - -
-------------
Span Elements
-------------
~~~~~
Links
~~~~~
Markdown supports two style of links: *inline* and *reference* by default.
In both styles, the link text is delimited by [square brackets].
Additionally, if enabled, Wiki Style Links are also supported, but
they are delimited by doubled square brackets (e.g. `[[wiki link]]`)
and have different semantics -- see the end of this section for that.
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.
Will produce:
This is
an example inline link.
This link has no
title attribute.
If you're referring to a local resource on the same server, you can
use relative paths:
See my [About](/about/) page for details.
Reference-style links use a second set of square brackets, inside
which you place a label of your choosing to identify the link:
This is [an example][id] reference-style link.
You can optionally use a space to separate the sets of brackets:
This is [an example] [id] reference-style link.
Then, anywhere in the document, you define your link label like this,
on a line by itself:
[id]: http://example.com/ "Optional Title Here"
That is:
* Square brackets containing the link identifier (optionally
indented from the left margin using up to three spaces);
* followed by a colon;
* followed by one or more spaces (or tabs);
* followed by the URL for the link;
* optionally followed by a title attribute for the link, enclosed
in double or single quotes, or enclosed in parentheses.
The following three link definitions are equivalent:
[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Optional Title Here'
[foo]: http://example.com/ (Optional Title Here)
**Note:** There is a known bug in Markdown.pl 1.0.3 which prevents
single quotes from being used to delimit link titles.
The link URL may, optionally, be surrounded by angle brackets:
[id]: "Optional Title Here"
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:
[id]: http://example.com/longish/path/to/resource/here
"Optional Title Here"
Link definitions are only used for creating links during Markdown
processing, and are stripped from your document in the HTML output.
Link definition names may consist of letters, numbers, spaces, and
punctuation -- but they are *not* case sensitive. E.g. these two
links:
[link text][a]
[link text][A]
are equivalent.
The *implicit link name* shortcut allows you to omit the name of the
link, in which case the link text itself is used as the name.
Just use an empty set of square brackets (or none) -- e.g., to link the
word "Google" to the google.com web site, you could simply write:
[Google][]
Or even just this:
[Google]
And then define the link:
[Google]: http://google.com/
Because link names may contain spaces, this shortcut even works for
multiple words in the link text:
Visit [Daring Fireball] for more information.
And then define the link:
[Daring Fireball]: http://daringfireball.net/
Text inside square brackets is left completely unchanged (including the
surrounding brackets) _unless_ it matches a link definition. Furthermore,
the single pair of surrounding square brackets case is always checked
for last so you may only omit the trailing `[]` of an *implicit link name*
shortcut when the result would still be unambiguous.
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.
All first, second and third level headers defined at the top-level
(in other words they are not in lists and start at the left margin)
using either the setext-style or atx-style automatically have an
anchor id and link definition added for them provided there is not
already a previous definition with the same id. You can use this
to place a table-of-contents at the top of the document that links
to subsections later in the document. Just like this document.
For example, all six of these links point to subsections later in
the same document:
* Self Same
* [Introduction]
* [Part Two]
* [Part Three]
* Different
* [Introduction](#Part-Two)
* [Part Two](#Part_Three)
* [Part Three](#introduction)
## Introduction
## Part Two
## Part Three
Here's an example of reference links in action:
I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
Using the implicit link name shortcut, you could instead write:
I get 10 times more traffic from [Google] than from
[Yahoo] or [MSN].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
Both of the above examples will produce the following HTML output:
I get 10 times more traffic from Google than from
Yahoo
or MSN.
For comparison, here is the same paragraph written using
Markdown's inline link style:
I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").
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.
#### Wiki Style Links
To create a wiki style link, simply use double brackets instead of
single brackets like so:
[[wiki link]]
[[wiki link|alternate_destination]]
Even when not explicitly enabled, a few, limited, wiki style links
are always recognized:
[[http://example.com]]
[[link here|http://example.com]]
[[link here|#destination]]
The "http:" part can also be "https:", "ftp:" and "ftps:". The
three above links generate these "a" tags:
http://example.com
link here
link here
If full wiki style links have been enabled (via the `--wiki` option),
then additional links like these will work too:
[[another page]]
[[link here|another page]]
[[elsewhere#section]]
[[link here|elsewhere#section]]
They will all generate "a" tags and are intended to link to another
document. Exactly what link is generated depends on the value
passed to the `--wiki` option. Using the default value, those four
links above would generate these "a" tags:
another page
link here
elsewhere#section
link here
See the command line help (`Markdown.pl --help`) for more details
on exactly how the wiki style links are transformed into "a" tags.
~~~~~~~~
Emphasis
~~~~~~~~
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. Double `~`'s will be wrapped with an HTML `` tag.
E.g., this input:
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
~~double tildes~~
will produce:
single asterisks
single underscores
double asterisks
double underscores
strike through
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.
Additionally `_` and double `_` are not recognized within words.
Emphasis using `*`'s or `~`'s can be used in the middle of a word:
un*frigging*believable fan~~frigging~~tastic
But if you surround an `*`, `_` or `~` with spaces, it'll be treated as a
literal asterisk, underscore or tilde.
To produce a literal asterisk, underscore or tilde at a position where it
would otherwise be used as an emphasis delimiter, you can backslash
escape it:
\*this text is surrounded by literal asterisks\*
~~~~
Code
~~~~
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:
Use the `printf()` function.
will produce:
Use the printf()
function.
To include a literal backtick character within a code span, you can use
multiple backticks as the opening and closing delimiters:
``There is a literal backtick (`) here.``
which will produce this:
There is a literal backtick (`) here.
The backtick delimiters surrounding a code span may include spaces --
one after the opening, one before the closing. This allows you to place
literal backtick characters at the beginning or end of a code span:
A single backtick in a code span: `` ` ``
A backtick-delimited string in a code span: `` `foo` ``
will produce:
A single backtick in a code span: `
A backtick-delimited string in a code span: `foo`
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:
Please don't use any `