1# Markdown: Syntax
2
3- [Overview](#overview)
4 - [Philosophy](#philosophy)
5 - [Inline HTML](#html)
6 - [Automatic Escaping for Special Characters](#autoescape)
7- [Block Elements](#block)
8 - [Paragraphs and Line Breaks](#p)
9 - [Headers](#header)
10 - [Blockquotes](#blockquote)
11 - [Lists](#list)
12 - [Code Blocks](#precode)
13 - [Horizontal Rules](#hr)
14- [Span Elements](#span)
15 - [Links](#link)
16 - [Emphasis](#em)
17 - [Code](#code)
18 - [Images](#img)
19- [Miscellaneous](#misc)
20 - [Backslash Escapes](#backslash)
21 - [Automatic Links](#autolink)
22
23**Note:** This document is itself written using Markdown; you
24can [see the source for it by adding '.text' to the URL](/projects/markdown/syntax.text).
25
26---
27
28## Overview
29
30### Philosophy
31
32Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
33
34Readability, however, is emphasized above all else. A Markdown-formatted
35document should be publishable as-is, as plain text, without looking
36like it's been marked up with tags or formatting instructions. While
37Markdown's syntax has been influenced by several existing text-to-HTML
38filters -- including [Setext](http://docutils.sourceforge.net/mirror/setext.html), [atx](http://www.aaronsw.com/2002/atx/), [Textile](http://textism.com/tools/textile/), [reStructuredText](http://docutils.sourceforge.net/rst.html),
39[Grutatext](http://www.triptico.com/software/grutatxt.html), and [EtText](http://ettext.taint.org/doc/) -- the single biggest source of
40inspiration for Markdown's syntax is the format of plain text email.
41
42## Block Elements
43
44### Paragraphs and Line Breaks
45
46A paragraph is simply one or more consecutive lines of text, separated
47by one or more blank lines. (A blank line is any line that looks like a
48blank line -- a line containing nothing but spaces or tabs is considered
49blank.) Normal paragraphs should not be indented with spaces or tabs.
50
51The implication of the "one or more consecutive lines of text" rule is
52that Markdown supports "hard-wrapped" text paragraphs. This differs
53significantly from most other text-to-HTML formatters (including Movable
54Type's "Convert Line Breaks" option) which translate every line break
55end a line with two or more spaces, then type return.
56
57### Headers
58
59Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
60
61Optionally, you may "close" atx-style headers. This is purely
62cosmetic -- you can use this if you think it looks better. The
63closing hashes don't even need to match the number of hashes
64used to open the header. (The number of opening hashes
65determines the header level.)
66
67### Blockquotes
68
69familiar with quoting passages of text in an email message, then you
70know how to create a blockquote in Markdown. It looks best if you hard
71
72> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
73> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
74> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
75>
76> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
77> id sem consectetuer libero luctus adipiscing.
78
79line of a hard-wrapped paragraph:
80
81> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
82> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
83> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
84
85> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
86> id sem consectetuer libero luctus adipiscing.
87
88Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
89
90> This is the first level of quoting.
91>
92> > This is nested blockquote.
93>
94> Back to the first level.
95
96Blockquotes can contain other Markdown elements, including headers, lists,
97and code blocks:
98
99> ## This is a header.
100>
101> 1. This is the first list item.
102> 2. This is the second list item.
103>
104> Here's some example code:
105>
106> return shell_exec("echo $input $markdown_script");
107
108Any decent text editor should make email-style quoting easy. For
109example, with BBEdit, you can make a selection and choose Increase
110Quote Level from the Text menu.
111
112### Lists
113
114Markdown supports ordered (numbered) and unordered (bulleted) lists.
115
116Unordered lists use asterisks, pluses, and hyphens -- interchangably
117-- as list markers:
118
119- Red
120- Green
121- Blue
122
123is equivalent to:
124
125- Red
126- Green
127- Blue
128
129and:
130
131- Red
132- Green
133- Blue
134
135Ordered lists use numbers followed by periods:
136
1371. Bird
1382. McHale
1393. Parish
140
141It's important to note that the actual numbers you use to mark the
142list have no effect on the HTML output Markdown produces. The HTML
143Markdown produces from the above list is:
144
145If you instead wrote the list in Markdown like this:
146
1471. Bird
1481. McHale
1491. Parish
150
151or even:
152
1533. Bird
1541. McHale
1551. Parish
156
157you'd get the exact same HTML output. The point is, if you want to,
158you can use ordinal numbers in your ordered Markdown lists, so that
159the numbers in your source match the numbers in your published HTML.
160But if you want to be lazy, you don't have to.
161
162To make lists look nice, you can wrap items with hanging indents:
163
164- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
165 Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
166 viverra nec, fringilla in, laoreet vitae, risus.
167- Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
168 Suspendisse id sem consectetuer libero luctus adipiscing.
169
170But if you want to be lazy, you don't have to:
171
172- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
173 Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
174 viverra nec, fringilla in, laoreet vitae, risus.
175- Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
176 Suspendisse id sem consectetuer libero luctus adipiscing.
177
178List items may consist of multiple paragraphs. Each subsequent
179paragraph in a list item must be indented by either 4 spaces
180or one tab:
181
1821. This is a list item with two paragraphs. Lorem ipsum dolor
183 sit amet, consectetuer adipiscing elit. Aliquam hendrerit
184 mi posuere lectus.
185
186 Vestibulum enim wisi, viverra nec, fringilla in, laoreet
187 vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
188 sit amet velit.
189
1902. Suspendisse id sem consectetuer libero luctus adipiscing.
191
192It looks nice if you indent every line of the subsequent
193paragraphs, but here again, Markdown will allow you to be
194lazy:
195
196- This is a list item with two paragraphs.
197
198 This is the second paragraph in the list item. You're
199
200 only required to indent the first line. Lorem ipsum dolor
201 sit amet, consectetuer adipiscing elit.
202
203- Another item in the same list.
204
205delimiters need to be indented:
206
207- A list item with a blockquote:
208
209 > This is a blockquote
210 > inside a list item.
211
212To put a code block within a list item, the code block needs
213to be indented _twice_ -- 8 spaces or two tabs:
214
215- A list item with a code block:
216
217### Code Blocks
218
219Pre-formatted code blocks are used for writing about programming or
220markup source code. Rather than forming normal paragraphs, the lines
221of a code block are interpreted literally. Markdown wraps a code block
222
223To produce a code block in Markdown, simply indent every line of the
224block by at least 4 spaces or 1 tab.
225
226This is a normal paragraph:
227
228 This is a code block.
229
230Here is an example of AppleScript:
231
232 tell application "Foo"
233 beep
234 end tell
235
236A code block continues until it reaches a line that is not indented
237(or the end of the article).
238
239are automatically converted into HTML entities. This makes it very
240easy to include example HTML source code using Markdown -- just paste
241it and indent it, and Markdown will handle the hassle of encoding the
242ampersands and angle brackets. For example, this:
243
244Regular Markdown syntax is not processed within code blocks. E.g.,
245asterisks are just literal asterisks within a code block. This means
246it's also easy to use Markdown to write about Markdown's own syntax.
247
248## Span Elements
249
250### Links
251
252Markdown supports two style of links: _inline_ and _reference_.
253
254In both styles, the link text is delimited by [square brackets].
255
256To create an inline link, use a set of regular parentheses immediately
257after the link text's closing square bracket. Inside the parentheses,
258put the URL where you want the link to point, along with an _optional_
259title for the link, surrounded in quotes. For example:
260
261This is [an example](http://example.com/) inline link.
262
263[This link](http://example.net/) has no title attribute.
264
265### Emphasis
266
267_single asterisks_
268
269_single underscores_
270
271**double asterisks**
272
273**double underscores**
274
275### Code
276
277Unlike a pre-formatted code block, a code span indicates code within a
278normal paragraph. For example:
View as plain text