bluecloth 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (103) hide show
  1. data/ChangeLog +629 -0
  2. data/LICENSE +27 -0
  3. data/LICENSE.discount +47 -0
  4. data/README +71 -0
  5. data/Rakefile +319 -0
  6. data/Rakefile.local +63 -0
  7. data/bin/bluecloth +84 -0
  8. data/ext/VERSION +1 -0
  9. data/ext/amalloc.h +29 -0
  10. data/ext/bluecloth.c +373 -0
  11. data/ext/config.h +47 -0
  12. data/ext/cstring.h +73 -0
  13. data/ext/docheader.c +43 -0
  14. data/ext/extconf.rb +45 -0
  15. data/ext/generate.c +1387 -0
  16. data/ext/markdown.c +939 -0
  17. data/ext/markdown.h +135 -0
  18. data/ext/mkdio.c +241 -0
  19. data/ext/mkdio.h +66 -0
  20. data/ext/resource.c +169 -0
  21. data/ext/version.c +28 -0
  22. data/lib/bluecloth.rb +148 -0
  23. data/rake/191_compat.rb +26 -0
  24. data/rake/dependencies.rb +76 -0
  25. data/rake/helpers.rb +412 -0
  26. data/rake/manual.rb +782 -0
  27. data/rake/packaging.rb +116 -0
  28. data/rake/publishing.rb +321 -0
  29. data/rake/rdoc.rb +40 -0
  30. data/rake/style.rb +62 -0
  31. data/rake/svn.rb +639 -0
  32. data/rake/testing.rb +204 -0
  33. data/rake/verifytask.rb +64 -0
  34. data/rake/win32.rb +186 -0
  35. data/spec/bluecloth/101_changes_spec.rb +141 -0
  36. data/spec/bluecloth/autolinks_spec.rb +49 -0
  37. data/spec/bluecloth/blockquotes_spec.rb +143 -0
  38. data/spec/bluecloth/code_spans_spec.rb +164 -0
  39. data/spec/bluecloth/emphasis_spec.rb +164 -0
  40. data/spec/bluecloth/entities_spec.rb +65 -0
  41. data/spec/bluecloth/hrules_spec.rb +90 -0
  42. data/spec/bluecloth/images_spec.rb +92 -0
  43. data/spec/bluecloth/inline_html_spec.rb +238 -0
  44. data/spec/bluecloth/links_spec.rb +171 -0
  45. data/spec/bluecloth/lists_spec.rb +294 -0
  46. data/spec/bluecloth/paragraphs_spec.rb +75 -0
  47. data/spec/bluecloth/titles_spec.rb +305 -0
  48. data/spec/bluecloth_spec.rb +209 -0
  49. data/spec/bugfix_spec.rb +123 -0
  50. data/spec/contributions_spec.rb +85 -0
  51. data/spec/data/antsugar.txt +34 -0
  52. data/spec/data/markdowntest/Amps and angle encoding.html +17 -0
  53. data/spec/data/markdowntest/Amps and angle encoding.text +21 -0
  54. data/spec/data/markdowntest/Auto links.html +18 -0
  55. data/spec/data/markdowntest/Auto links.text +13 -0
  56. data/spec/data/markdowntest/Backslash escapes.html +118 -0
  57. data/spec/data/markdowntest/Backslash escapes.text +120 -0
  58. data/spec/data/markdowntest/Blockquotes with code blocks.html +15 -0
  59. data/spec/data/markdowntest/Blockquotes with code blocks.text +11 -0
  60. data/spec/data/markdowntest/Code Blocks.html +18 -0
  61. data/spec/data/markdowntest/Code Blocks.text +14 -0
  62. data/spec/data/markdowntest/Code Spans.html +5 -0
  63. data/spec/data/markdowntest/Code Spans.text +5 -0
  64. data/spec/data/markdowntest/Hard-wrapped paragraphs with list-like lines.html +8 -0
  65. data/spec/data/markdowntest/Hard-wrapped paragraphs with list-like lines.text +8 -0
  66. data/spec/data/markdowntest/Horizontal rules.html +71 -0
  67. data/spec/data/markdowntest/Horizontal rules.text +67 -0
  68. data/spec/data/markdowntest/Inline HTML (Advanced).html +15 -0
  69. data/spec/data/markdowntest/Inline HTML (Advanced).text +15 -0
  70. data/spec/data/markdowntest/Inline HTML (Simple).html +72 -0
  71. data/spec/data/markdowntest/Inline HTML (Simple).text +69 -0
  72. data/spec/data/markdowntest/Inline HTML comments.html +13 -0
  73. data/spec/data/markdowntest/Inline HTML comments.text +13 -0
  74. data/spec/data/markdowntest/Links, inline style.html +11 -0
  75. data/spec/data/markdowntest/Links, inline style.text +12 -0
  76. data/spec/data/markdowntest/Links, reference style.html +52 -0
  77. data/spec/data/markdowntest/Links, reference style.text +71 -0
  78. data/spec/data/markdowntest/Links, shortcut references.html +9 -0
  79. data/spec/data/markdowntest/Links, shortcut references.text +20 -0
  80. data/spec/data/markdowntest/Literal quotes in titles.html +3 -0
  81. data/spec/data/markdowntest/Literal quotes in titles.text +7 -0
  82. data/spec/data/markdowntest/Markdown Documentation - Basics.html +314 -0
  83. data/spec/data/markdowntest/Markdown Documentation - Basics.text +306 -0
  84. data/spec/data/markdowntest/Markdown Documentation - Syntax.html +942 -0
  85. data/spec/data/markdowntest/Markdown Documentation - Syntax.text +888 -0
  86. data/spec/data/markdowntest/Nested blockquotes.html +9 -0
  87. data/spec/data/markdowntest/Nested blockquotes.text +5 -0
  88. data/spec/data/markdowntest/Ordered and unordered lists.html +148 -0
  89. data/spec/data/markdowntest/Ordered and unordered lists.text +131 -0
  90. data/spec/data/markdowntest/Strong and em together.html +7 -0
  91. data/spec/data/markdowntest/Strong and em together.text +7 -0
  92. data/spec/data/markdowntest/Tabs.html +25 -0
  93. data/spec/data/markdowntest/Tabs.text +21 -0
  94. data/spec/data/markdowntest/Tidyness.html +8 -0
  95. data/spec/data/markdowntest/Tidyness.text +5 -0
  96. data/spec/data/ml-announce.txt +17 -0
  97. data/spec/data/re-overflow.txt +67 -0
  98. data/spec/data/re-overflow2.txt +281 -0
  99. data/spec/lib/constants.rb +5 -0
  100. data/spec/lib/helpers.rb +137 -0
  101. data/spec/lib/matchers.rb +235 -0
  102. data/spec/markdowntest_spec.rb +76 -0
  103. metadata +305 -0
@@ -0,0 +1,306 @@
1
+ Markdown: Basics
2
+ ================
3
+
4
+ <ul id="ProjectSubmenu">
5
+ <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
6
+ <li><a class="selected" title="Markdown Basics">Basics</a></li>
7
+ <li><a href="/projects/markdown/syntax" title="Markdown Syntax Documentation">Syntax</a></li>
8
+ <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
9
+ <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
10
+ </ul>
11
+
12
+
13
+ Getting the Gist of Markdown's Formatting Syntax
14
+ ------------------------------------------------
15
+
16
+ This page offers a brief overview of what it's like to use Markdown.
17
+ The [syntax page] [s] provides complete, detailed documentation for
18
+ every feature, but Markdown should be very easy to pick up simply by
19
+ looking at a few examples of it in action. The examples on this page
20
+ are written in a before/after style, showing example syntax and the
21
+ HTML output produced by Markdown.
22
+
23
+ It's also helpful to simply try Markdown out; the [Dingus] [d] is a
24
+ web application that allows you type your own Markdown-formatted text
25
+ and translate it to XHTML.
26
+
27
+ **Note:** This document is itself written using Markdown; you
28
+ can [see the source for it by adding '.text' to the URL] [src].
29
+
30
+ [s]: /projects/markdown/syntax "Markdown Syntax"
31
+ [d]: /projects/markdown/dingus "Markdown Dingus"
32
+ [src]: /projects/markdown/basics.text
33
+
34
+
35
+ ## Paragraphs, Headers, Blockquotes ##
36
+
37
+ A paragraph is simply one or more consecutive lines of text, separated
38
+ by one or more blank lines. (A blank line is any line that looks like a
39
+ blank line -- a line containing nothing spaces or tabs is considered
40
+ blank.) Normal paragraphs should not be intended with spaces or tabs.
41
+
42
+ Markdown offers two styles of headers: *Setext* and *atx*.
43
+ Setext-style headers for `<h1>` and `<h2>` are created by
44
+ "underlining" with equal signs (`=`) and hyphens (`-`), respectively.
45
+ To create an atx-style header, you put 1-6 hash marks (`#`) at the
46
+ beginning of the line -- the number of hashes equals the resulting
47
+ HTML header level.
48
+
49
+ Blockquotes are indicated using email-style '`>`' angle brackets.
50
+
51
+ Markdown:
52
+
53
+ A First Level Header
54
+ ====================
55
+
56
+ A Second Level Header
57
+ ---------------------
58
+
59
+ Now is the time for all good men to come to
60
+ the aid of their country. This is just a
61
+ regular paragraph.
62
+
63
+ The quick brown fox jumped over the lazy
64
+ dog's back.
65
+
66
+ ### Header 3
67
+
68
+ > This is a blockquote.
69
+ >
70
+ > This is the second paragraph in the blockquote.
71
+ >
72
+ > ## This is an H2 in a blockquote
73
+
74
+
75
+ Output:
76
+
77
+ <h1>A First Level Header</h1>
78
+
79
+ <h2>A Second Level Header</h2>
80
+
81
+ <p>Now is the time for all good men to come to
82
+ the aid of their country. This is just a
83
+ regular paragraph.</p>
84
+
85
+ <p>The quick brown fox jumped over the lazy
86
+ dog's back.</p>
87
+
88
+ <h3>Header 3</h3>
89
+
90
+ <blockquote>
91
+ <p>This is a blockquote.</p>
92
+
93
+ <p>This is the second paragraph in the blockquote.</p>
94
+
95
+ <h2>This is an H2 in a blockquote</h2>
96
+ </blockquote>
97
+
98
+
99
+
100
+ ### Phrase Emphasis ###
101
+
102
+ Markdown uses asterisks and underscores to indicate spans of emphasis.
103
+
104
+ Markdown:
105
+
106
+ Some of these words *are emphasized*.
107
+ Some of these words _are emphasized also_.
108
+
109
+ Use two asterisks for **strong emphasis**.
110
+ Or, if you prefer, __use two underscores instead__.
111
+
112
+ Output:
113
+
114
+ <p>Some of these words <em>are emphasized</em>.
115
+ Some of these words <em>are emphasized also</em>.</p>
116
+
117
+ <p>Use two asterisks for <strong>strong emphasis</strong>.
118
+ Or, if you prefer, <strong>use two underscores instead</strong>.</p>
119
+
120
+
121
+
122
+ ## Lists ##
123
+
124
+ Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
125
+ `+`, and `-`) as list markers. These three markers are
126
+ interchangable; this:
127
+
128
+ * Candy.
129
+ * Gum.
130
+ * Booze.
131
+
132
+ this:
133
+
134
+ + Candy.
135
+ + Gum.
136
+ + Booze.
137
+
138
+ and this:
139
+
140
+ - Candy.
141
+ - Gum.
142
+ - Booze.
143
+
144
+ all produce the same output:
145
+
146
+ <ul>
147
+ <li>Candy.</li>
148
+ <li>Gum.</li>
149
+ <li>Booze.</li>
150
+ </ul>
151
+
152
+ Ordered (numbered) lists use regular numbers, followed by periods, as
153
+ list markers:
154
+
155
+ 1. Red
156
+ 2. Green
157
+ 3. Blue
158
+
159
+ Output:
160
+
161
+ <ol>
162
+ <li>Red</li>
163
+ <li>Green</li>
164
+ <li>Blue</li>
165
+ </ol>
166
+
167
+ If you put blank lines between items, you'll get `<p>` tags for the
168
+ list item text. You can create multi-paragraph list items by indenting
169
+ the paragraphs by 4 spaces or 1 tab:
170
+
171
+ * A list item.
172
+
173
+ With multiple paragraphs.
174
+
175
+ * Another item in the list.
176
+
177
+ Output:
178
+
179
+ <ul>
180
+ <li><p>A list item.</p>
181
+ <p>With multiple paragraphs.</p></li>
182
+ <li><p>Another item in the list.</p></li>
183
+ </ul>
184
+
185
+
186
+
187
+ ### Links ###
188
+
189
+ Markdown supports two styles for creating links: *inline* and
190
+ *reference*. With both styles, you use square brackets to delimit the
191
+ text you want to turn into a link.
192
+
193
+ Inline-style links use parentheses immediately after the link text.
194
+ For example:
195
+
196
+ This is an [example link](http://example.com/).
197
+
198
+ Output:
199
+
200
+ <p>This is an <a href="http://example.com/">
201
+ example link</a>.</p>
202
+
203
+ Optionally, you may include a title attribute in the parentheses:
204
+
205
+ This is an [example link](http://example.com/ "With a Title").
206
+
207
+ Output:
208
+
209
+ <p>This is an <a href="http://example.com/" title="With a Title">
210
+ example link</a>.</p>
211
+
212
+ Reference-style links allow you to refer to your links by names, which
213
+ you define elsewhere in your document:
214
+
215
+ I get 10 times more traffic from [Google][1] than from
216
+ [Yahoo][2] or [MSN][3].
217
+
218
+ [1]: http://google.com/ "Google"
219
+ [2]: http://search.yahoo.com/ "Yahoo Search"
220
+ [3]: http://search.msn.com/ "MSN Search"
221
+
222
+ Output:
223
+
224
+ <p>I get 10 times more traffic from <a href="http://google.com/"
225
+ title="Google">Google</a> than from <a href="http://search.yahoo.com/"
226
+ title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
227
+ title="MSN Search">MSN</a>.</p>
228
+
229
+ The title attribute is optional. Link names may contain letters,
230
+ numbers and spaces, but are *not* case sensitive:
231
+
232
+ I start my morning with a cup of coffee and
233
+ [The New York Times][NY Times].
234
+
235
+ [ny times]: http://www.nytimes.com/
236
+
237
+ Output:
238
+
239
+ <p>I start my morning with a cup of coffee and
240
+ <a href="http://www.nytimes.com/">The New York Times</a>.</p>
241
+
242
+
243
+ ### Images ###
244
+
245
+ Image syntax is very much like link syntax.
246
+
247
+ Inline (titles are optional):
248
+
249
+ ![alt text](/path/to/img.jpg "Title")
250
+
251
+ Reference-style:
252
+
253
+ ![alt text][id]
254
+
255
+ [id]: /path/to/img.jpg "Title"
256
+
257
+ Both of the above examples produce the same output:
258
+
259
+ <img src="/path/to/img.jpg" alt="alt text" title="Title" />
260
+
261
+
262
+
263
+ ### Code ###
264
+
265
+ In a regular paragraph, you can create code span by wrapping text in
266
+ backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
267
+ `>`) will automatically be translated into HTML entities. This makes
268
+ it easy to use Markdown to write about HTML example code:
269
+
270
+ I strongly recommend against using any `<blink>` tags.
271
+
272
+ I wish SmartyPants used named entities like `&mdash;`
273
+ instead of decimal-encoded entites like `&#8212;`.
274
+
275
+ Output:
276
+
277
+ <p>I strongly recommend against using any
278
+ <code>&lt;blink&gt;</code> tags.</p>
279
+
280
+ <p>I wish SmartyPants used named entities like
281
+ <code>&amp;mdash;</code> instead of decimal-encoded
282
+ entites like <code>&amp;#8212;</code>.</p>
283
+
284
+
285
+ To specify an entire block of pre-formatted code, indent every line of
286
+ the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
287
+ and `>` characters will be escaped automatically.
288
+
289
+ Markdown:
290
+
291
+ If you want your page to validate under XHTML 1.0 Strict,
292
+ you've got to put paragraph tags in your blockquotes:
293
+
294
+ <blockquote>
295
+ <p>For example.</p>
296
+ </blockquote>
297
+
298
+ Output:
299
+
300
+ <p>If you want your page to validate under XHTML 1.0 Strict,
301
+ you've got to put paragraph tags in your blockquotes:</p>
302
+
303
+ <pre><code>&lt;blockquote&gt;
304
+ &lt;p&gt;For example.&lt;/p&gt;
305
+ &lt;/blockquote&gt;
306
+ </code></pre>
@@ -0,0 +1,942 @@
1
+ <h1>Markdown: Syntax</h1>
2
+
3
+ <ul id="ProjectSubmenu">
4
+ <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
5
+ <li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
6
+ <li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
7
+ <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
8
+ <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
9
+ </ul>
10
+
11
+ <ul>
12
+ <li><a href="#overview">Overview</a>
13
+ <ul>
14
+ <li><a href="#philosophy">Philosophy</a></li>
15
+ <li><a href="#html">Inline HTML</a></li>
16
+ <li><a href="#autoescape">Automatic Escaping for Special Characters</a></li>
17
+ </ul></li>
18
+ <li><a href="#block">Block Elements</a>
19
+ <ul>
20
+ <li><a href="#p">Paragraphs and Line Breaks</a></li>
21
+ <li><a href="#header">Headers</a></li>
22
+ <li><a href="#blockquote">Blockquotes</a></li>
23
+ <li><a href="#list">Lists</a></li>
24
+ <li><a href="#precode">Code Blocks</a></li>
25
+ <li><a href="#hr">Horizontal Rules</a></li>
26
+ </ul></li>
27
+ <li><a href="#span">Span Elements</a>
28
+ <ul>
29
+ <li><a href="#link">Links</a></li>
30
+ <li><a href="#em">Emphasis</a></li>
31
+ <li><a href="#code">Code</a></li>
32
+ <li><a href="#img">Images</a></li>
33
+ </ul></li>
34
+ <li><a href="#misc">Miscellaneous</a>
35
+ <ul>
36
+ <li><a href="#backslash">Backslash Escapes</a></li>
37
+ <li><a href="#autolink">Automatic Links</a></li>
38
+ </ul></li>
39
+ </ul>
40
+
41
+ <p><strong>Note:</strong> This document is itself written using Markdown; you
42
+ can <a href="/projects/markdown/syntax.text">see the source for it by adding '.text' to the URL</a>.</p>
43
+
44
+ <hr />
45
+
46
+ <h2 id="overview">Overview</h2>
47
+
48
+ <h3 id="philosophy">Philosophy</h3>
49
+
50
+ <p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.</p>
51
+
52
+ <p>Readability, however, is emphasized above all else. A Markdown-formatted
53
+ document should be publishable as-is, as plain text, without looking
54
+ like it's been marked up with tags or formatting instructions. While
55
+ Markdown's syntax has been influenced by several existing text-to-HTML
56
+ filters -- including <a href="http://docutils.sourceforge.net/mirror/setext.html">Setext</a>, <a href="http://www.aaronsw.com/2002/atx/">atx</a>, <a href="http://textism.com/tools/textile/">Textile</a>, <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>,
57
+ <a href="http://www.triptico.com/software/grutatxt.html">Grutatext</a>, and <a href="http://ettext.taint.org/doc/">EtText</a> -- the single biggest source of
58
+ inspiration for Markdown's syntax is the format of plain text email.</p>
59
+
60
+ <p>To this end, Markdown's syntax is comprised entirely of punctuation
61
+ characters, which punctuation characters have been carefully chosen so
62
+ as to look like what they mean. E.g., asterisks around a word actually
63
+ look like *emphasis*. Markdown lists look like, well, lists. Even
64
+ blockquotes look like quoted passages of text, assuming you've ever
65
+ used email.</p>
66
+
67
+ <h3 id="html">Inline HTML</h3>
68
+
69
+ <p>Markdown's syntax is intended for one purpose: to be used as a
70
+ format for <em>writing</em> for the web.</p>
71
+
72
+ <p>Markdown is not a replacement for HTML, or even close to it. Its
73
+ syntax is very small, corresponding only to a very small subset of
74
+ HTML tags. The idea is <em>not</em> to create a syntax that makes it easier
75
+ to insert HTML tags. In my opinion, HTML tags are already easy to
76
+ insert. The idea for Markdown is to make it easy to read, write, and
77
+ edit prose. HTML is a <em>publishing</em> format; Markdown is a <em>writing</em>
78
+ format. Thus, Markdown's formatting syntax only addresses issues that
79
+ can be conveyed in plain text.</p>
80
+
81
+ <p>For any markup that is not covered by Markdown's syntax, you simply
82
+ use HTML itself. There's no need to preface it or delimit it to
83
+ indicate that you're switching from Markdown to HTML; you just use
84
+ the tags.</p>
85
+
86
+ <p>The only restrictions are that block-level HTML elements -- e.g. <code>&lt;div&gt;</code>,
87
+ <code>&lt;table&gt;</code>, <code>&lt;pre&gt;</code>, <code>&lt;p&gt;</code>, etc. -- must be separated from surrounding
88
+ content by blank lines, and the start and end tags of the block should
89
+ not be indented with tabs or spaces. Markdown is smart enough not
90
+ to add extra (unwanted) <code>&lt;p&gt;</code> tags around HTML block-level tags.</p>
91
+
92
+ <p>For example, to add an HTML table to a Markdown article:</p>
93
+
94
+ <pre><code>This is a regular paragraph.
95
+
96
+ &lt;table&gt;
97
+ &lt;tr&gt;
98
+ &lt;td&gt;Foo&lt;/td&gt;
99
+ &lt;/tr&gt;
100
+ &lt;/table&gt;
101
+
102
+ This is another regular paragraph.
103
+ </code></pre>
104
+
105
+ <p>Note that Markdown formatting syntax is not processed within block-level
106
+ HTML tags. E.g., you can't use Markdown-style <code>*emphasis*</code> inside an
107
+ HTML block.</p>
108
+
109
+ <p>Span-level HTML tags -- e.g. <code>&lt;span&gt;</code>, <code>&lt;cite&gt;</code>, or <code>&lt;del&gt;</code> -- can be
110
+ used anywhere in a Markdown paragraph, list item, or header. If you
111
+ want, you can even use HTML tags instead of Markdown formatting; e.g. if
112
+ you'd prefer to use HTML <code>&lt;a&gt;</code> or <code>&lt;img&gt;</code> tags instead of Markdown's
113
+ link or image syntax, go right ahead.</p>
114
+
115
+ <p>Unlike block-level HTML tags, Markdown syntax <em>is</em> processed within
116
+ span-level tags.</p>
117
+
118
+ <h3 id="autoescape">Automatic Escaping for Special Characters</h3>
119
+
120
+ <p>In HTML, there are two characters that demand special treatment: <code>&lt;</code>
121
+ and <code>&amp;</code>. Left angle brackets are used to start tags; ampersands are
122
+ used to denote HTML entities. If you want to use them as literal
123
+ characters, you must escape them as entities, e.g. <code>&amp;lt;</code>, and
124
+ <code>&amp;amp;</code>.</p>
125
+
126
+ <p>Ampersands in particular are bedeviling for web writers. If you want to
127
+ write about 'AT&amp;T', you need to write '<code>AT&amp;amp;T</code>'. You even need to
128
+ escape ampersands within URLs. Thus, if you want to link to:</p>
129
+
130
+ <pre><code>http://images.google.com/images?num=30&amp;q=larry+bird
131
+ </code></pre>
132
+
133
+ <p>you need to encode the URL as:</p>
134
+
135
+ <pre><code>http://images.google.com/images?num=30&amp;amp;q=larry+bird
136
+ </code></pre>
137
+
138
+ <p>in your anchor tag <code>href</code> attribute. Needless to say, this is easy to
139
+ forget, and is probably the single most common source of HTML validation
140
+ errors in otherwise well-marked-up web sites.</p>
141
+
142
+ <p>Markdown allows you to use these characters naturally, taking care of
143
+ all the necessary escaping for you. If you use an ampersand as part of
144
+ an HTML entity, it remains unchanged; otherwise it will be translated
145
+ into <code>&amp;amp;</code>.</p>
146
+
147
+ <p>So, if you want to include a copyright symbol in your article, you can write:</p>
148
+
149
+ <pre><code>&amp;copy;
150
+ </code></pre>
151
+
152
+ <p>and Markdown will leave it alone. But if you write:</p>
153
+
154
+ <pre><code>AT&amp;T
155
+ </code></pre>
156
+
157
+ <p>Markdown will translate it to:</p>
158
+
159
+ <pre><code>AT&amp;amp;T
160
+ </code></pre>
161
+
162
+ <p>Similarly, because Markdown supports <a href="#html">inline HTML</a>, if you use
163
+ angle brackets as delimiters for HTML tags, Markdown will treat them as
164
+ such. But if you write:</p>
165
+
166
+ <pre><code>4 &lt; 5
167
+ </code></pre>
168
+
169
+ <p>Markdown will translate it to:</p>
170
+
171
+ <pre><code>4 &amp;lt; 5
172
+ </code></pre>
173
+
174
+ <p>However, inside Markdown code spans and blocks, angle brackets and
175
+ ampersands are <em>always</em> encoded automatically. This makes it easy to use
176
+ Markdown to write about HTML code. (As opposed to raw HTML, which is a
177
+ terrible format for writing about HTML syntax, because every single <code>&lt;</code>
178
+ and <code>&amp;</code> in your example code needs to be escaped.)</p>
179
+
180
+ <hr />
181
+
182
+ <h2 id="block">Block Elements</h2>
183
+
184
+ <h3 id="p">Paragraphs and Line Breaks</h3>
185
+
186
+ <p>A paragraph is simply one or more consecutive lines of text, separated
187
+ by one or more blank lines. (A blank line is any line that looks like a
188
+ blank line -- a line containing nothing but spaces or tabs is considered
189
+ blank.) Normal paragraphs should not be intended with spaces or tabs.</p>
190
+
191
+ <p>The implication of the "one or more consecutive lines of text" rule is
192
+ that Markdown supports "hard-wrapped" text paragraphs. This differs
193
+ significantly from most other text-to-HTML formatters (including Movable
194
+ Type's "Convert Line Breaks" option) which translate every line break
195
+ character in a paragraph into a <code>&lt;br /&gt;</code> tag.</p>
196
+
197
+ <p>When you <em>do</em> want to insert a <code>&lt;br /&gt;</code> break tag using Markdown, you
198
+ end a line with two or more spaces, then type return.</p>
199
+
200
+ <p>Yes, this takes a tad more effort to create a <code>&lt;br /&gt;</code>, but a simplistic
201
+ "every line break is a <code>&lt;br /&gt;</code>" rule wouldn't work for Markdown.
202
+ Markdown's email-style <a href="#blockquote">blockquoting</a> and multi-paragraph <a href="#list">list items</a>
203
+ work best -- and look better -- when you format them with hard breaks.</p>
204
+
205
+ <h3 id="header">Headers</h3>
206
+
207
+ <p>Markdown supports two styles of headers, <a href="http://docutils.sourceforge.net/mirror/setext.html">Setext</a> and <a href="http://www.aaronsw.com/2002/atx/">atx</a>.</p>
208
+
209
+ <p>Setext-style headers are "underlined" using equal signs (for first-level
210
+ headers) and dashes (for second-level headers). For example:</p>
211
+
212
+ <pre><code>This is an H1
213
+ =============
214
+
215
+ This is an H2
216
+ -------------
217
+ </code></pre>
218
+
219
+ <p>Any number of underlining <code>=</code>'s or <code>-</code>'s will work.</p>
220
+
221
+ <p>Atx-style headers use 1-6 hash characters at the start of the line,
222
+ corresponding to header levels 1-6. For example:</p>
223
+
224
+ <pre><code># This is an H1
225
+
226
+ ## This is an H2
227
+
228
+ ###### This is an H6
229
+ </code></pre>
230
+
231
+ <p>Optionally, you may "close" atx-style headers. This is purely
232
+ cosmetic -- you can use this if you think it looks better. The
233
+ closing hashes don't even need to match the number of hashes
234
+ used to open the header. (The number of opening hashes
235
+ determines the header level.) :</p>
236
+
237
+ <pre><code># This is an H1 #
238
+
239
+ ## This is an H2 ##
240
+
241
+ ### This is an H3 ######
242
+ </code></pre>
243
+
244
+ <h3 id="blockquote">Blockquotes</h3>
245
+
246
+ <p>Markdown uses email-style <code>&gt;</code> characters for blockquoting. If you're
247
+ familiar with quoting passages of text in an email message, then you
248
+ know how to create a blockquote in Markdown. It looks best if you hard
249
+ wrap the text and put a <code>&gt;</code> before every line:</p>
250
+
251
+ <pre><code>&gt; This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
252
+ &gt; consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
253
+ &gt; Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
254
+ &gt;
255
+ &gt; Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
256
+ &gt; id sem consectetuer libero luctus adipiscing.
257
+ </code></pre>
258
+
259
+ <p>Markdown allows you to be lazy and only put the <code>&gt;</code> before the first
260
+ line of a hard-wrapped paragraph:</p>
261
+
262
+ <pre><code>&gt; This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
263
+ consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
264
+ Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
265
+
266
+ &gt; Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
267
+ id sem consectetuer libero luctus adipiscing.
268
+ </code></pre>
269
+
270
+ <p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
271
+ adding additional levels of <code>&gt;</code>:</p>
272
+
273
+ <pre><code>&gt; This is the first level of quoting.
274
+ &gt;
275
+ &gt; &gt; This is nested blockquote.
276
+ &gt;
277
+ &gt; Back to the first level.
278
+ </code></pre>
279
+
280
+ <p>Blockquotes can contain other Markdown elements, including headers, lists,
281
+ and code blocks:</p>
282
+
283
+ <pre><code>&gt; ## This is a header.
284
+ &gt;
285
+ &gt; 1. This is the first list item.
286
+ &gt; 2. This is the second list item.
287
+ &gt;
288
+ &gt; Here's some example code:
289
+ &gt;
290
+ &gt; return shell_exec("echo $input | $markdown_script");
291
+ </code></pre>
292
+
293
+ <p>Any decent text editor should make email-style quoting easy. For
294
+ example, with BBEdit, you can make a selection and choose Increase
295
+ Quote Level from the Text menu.</p>
296
+
297
+ <h3 id="list">Lists</h3>
298
+
299
+ <p>Markdown supports ordered (numbered) and unordered (bulleted) lists.</p>
300
+
301
+ <p>Unordered lists use asterisks, pluses, and hyphens -- interchangably
302
+ -- as list markers:</p>
303
+
304
+ <pre><code>* Red
305
+ * Green
306
+ * Blue
307
+ </code></pre>
308
+
309
+ <p>is equivalent to:</p>
310
+
311
+ <pre><code>+ Red
312
+ + Green
313
+ + Blue
314
+ </code></pre>
315
+
316
+ <p>and:</p>
317
+
318
+ <pre><code>- Red
319
+ - Green
320
+ - Blue
321
+ </code></pre>
322
+
323
+ <p>Ordered lists use numbers followed by periods:</p>
324
+
325
+ <pre><code>1. Bird
326
+ 2. McHale
327
+ 3. Parish
328
+ </code></pre>
329
+
330
+ <p>It's important to note that the actual numbers you use to mark the
331
+ list have no effect on the HTML output Markdown produces. The HTML
332
+ Markdown produces from the above list is:</p>
333
+
334
+ <pre><code>&lt;ol&gt;
335
+ &lt;li&gt;Bird&lt;/li&gt;
336
+ &lt;li&gt;McHale&lt;/li&gt;
337
+ &lt;li&gt;Parish&lt;/li&gt;
338
+ &lt;/ol&gt;
339
+ </code></pre>
340
+
341
+ <p>If you instead wrote the list in Markdown like this:</p>
342
+
343
+ <pre><code>1. Bird
344
+ 1. McHale
345
+ 1. Parish
346
+ </code></pre>
347
+
348
+ <p>or even:</p>
349
+
350
+ <pre><code>3. Bird
351
+ 1. McHale
352
+ 8. Parish
353
+ </code></pre>
354
+
355
+ <p>you'd get the exact same HTML output. The point is, if you want to,
356
+ you can use ordinal numbers in your ordered Markdown lists, so that
357
+ the numbers in your source match the numbers in your published HTML.
358
+ But if you want to be lazy, you don't have to.</p>
359
+
360
+ <p>If you do use lazy list numbering, however, you should still start the
361
+ list with the number 1. At some point in the future, Markdown may support
362
+ starting ordered lists at an arbitrary number.</p>
363
+
364
+ <p>List markers typically start at the left margin, but may be indented by
365
+ up to three spaces. List markers must be followed by one or more spaces
366
+ or a tab.</p>
367
+
368
+ <p>To make lists look nice, you can wrap items with hanging indents:</p>
369
+
370
+ <pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
371
+ Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
372
+ viverra nec, fringilla in, laoreet vitae, risus.
373
+ * Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
374
+ Suspendisse id sem consectetuer libero luctus adipiscing.
375
+ </code></pre>
376
+
377
+ <p>But if you want to be lazy, you don't have to:</p>
378
+
379
+ <pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
380
+ Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
381
+ viverra nec, fringilla in, laoreet vitae, risus.
382
+ * Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
383
+ Suspendisse id sem consectetuer libero luctus adipiscing.
384
+ </code></pre>
385
+
386
+ <p>If list items are separated by blank lines, Markdown will wrap the
387
+ items in <code>&lt;p&gt;</code> tags in the HTML output. For example, this input:</p>
388
+
389
+ <pre><code>* Bird
390
+ * Magic
391
+ </code></pre>
392
+
393
+ <p>will turn into:</p>
394
+
395
+ <pre><code>&lt;ul&gt;
396
+ &lt;li&gt;Bird&lt;/li&gt;
397
+ &lt;li&gt;Magic&lt;/li&gt;
398
+ &lt;/ul&gt;
399
+ </code></pre>
400
+
401
+ <p>But this:</p>
402
+
403
+ <pre><code>* Bird
404
+
405
+ * Magic
406
+ </code></pre>
407
+
408
+ <p>will turn into:</p>
409
+
410
+ <pre><code>&lt;ul&gt;
411
+ &lt;li&gt;&lt;p&gt;Bird&lt;/p&gt;&lt;/li&gt;
412
+ &lt;li&gt;&lt;p&gt;Magic&lt;/p&gt;&lt;/li&gt;
413
+ &lt;/ul&gt;
414
+ </code></pre>
415
+
416
+ <p>List items may consist of multiple paragraphs. Each subsequent
417
+ paragraph in a list item must be intended by either 4 spaces
418
+ or one tab:</p>
419
+
420
+ <pre><code>1. This is a list item with two paragraphs. Lorem ipsum dolor
421
+ sit amet, consectetuer adipiscing elit. Aliquam hendrerit
422
+ mi posuere lectus.
423
+
424
+ Vestibulum enim wisi, viverra nec, fringilla in, laoreet
425
+ vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
426
+ sit amet velit.
427
+
428
+ 2. Suspendisse id sem consectetuer libero luctus adipiscing.
429
+ </code></pre>
430
+
431
+ <p>It looks nice if you indent every line of the subsequent
432
+ paragraphs, but here again, Markdown will allow you to be
433
+ lazy:</p>
434
+
435
+ <pre><code>* This is a list item with two paragraphs.
436
+
437
+ This is the second paragraph in the list item. You're
438
+ only required to indent the first line. Lorem ipsum dolor
439
+ sit amet, consectetuer adipiscing elit.
440
+
441
+ * Another item in the same list.
442
+ </code></pre>
443
+
444
+ <p>To put a blockquote within a list item, the blockquote's <code>&gt;</code>
445
+ delimiters need to be indented:</p>
446
+
447
+ <pre><code>* A list item with a blockquote:
448
+
449
+ &gt; This is a blockquote
450
+ &gt; inside a list item.
451
+ </code></pre>
452
+
453
+ <p>To put a code block within a list item, the code block needs
454
+ to be indented <em>twice</em> -- 8 spaces or two tabs:</p>
455
+
456
+ <pre><code>* A list item with a code block:
457
+
458
+ &lt;code goes here&gt;
459
+ </code></pre>
460
+
461
+ <p>It's worth noting that it's possible to trigger an ordered list by
462
+ accident, by writing something like this:</p>
463
+
464
+ <pre><code>1986. What a great season.
465
+ </code></pre>
466
+
467
+ <p>In other words, a <em>number-period-space</em> sequence at the beginning of a
468
+ line. To avoid this, you can backslash-escape the period:</p>
469
+
470
+ <pre><code>1986\. What a great season.
471
+ </code></pre>
472
+
473
+ <h3 id="precode">Code Blocks</h3>
474
+
475
+ <p>Pre-formatted code blocks are used for writing about programming or
476
+ markup source code. Rather than forming normal paragraphs, the lines
477
+ of a code block are interpreted literally. Markdown wraps a code block
478
+ in both <code>&lt;pre&gt;</code> and <code>&lt;code&gt;</code> tags.</p>
479
+
480
+ <p>To produce a code block in Markdown, simply indent every line of the
481
+ block by at least 4 spaces or 1 tab. For example, given this input:</p>
482
+
483
+ <pre><code>This is a normal paragraph:
484
+
485
+ This is a code block.
486
+ </code></pre>
487
+
488
+ <p>Markdown will generate:</p>
489
+
490
+ <pre><code>&lt;p&gt;This is a normal paragraph:&lt;/p&gt;
491
+
492
+ &lt;pre&gt;&lt;code&gt;This is a code block.
493
+ &lt;/code&gt;&lt;/pre&gt;
494
+ </code></pre>
495
+
496
+ <p>One level of indentation -- 4 spaces or 1 tab -- is removed from each
497
+ line of the code block. For example, this:</p>
498
+
499
+ <pre><code>Here is an example of AppleScript:
500
+
501
+ tell application "Foo"
502
+ beep
503
+ end tell
504
+ </code></pre>
505
+
506
+ <p>will turn into:</p>
507
+
508
+ <pre><code>&lt;p&gt;Here is an example of AppleScript:&lt;/p&gt;
509
+
510
+ &lt;pre&gt;&lt;code&gt;tell application "Foo"
511
+ beep
512
+ end tell
513
+ &lt;/code&gt;&lt;/pre&gt;
514
+ </code></pre>
515
+
516
+ <p>A code block continues until it reaches a line that is not indented
517
+ (or the end of the article).</p>
518
+
519
+ <p>Within a code block, ampersands (<code>&amp;</code>) and angle brackets (<code>&lt;</code> and <code>&gt;</code>)
520
+ are automatically converted into HTML entities. This makes it very
521
+ easy to include example HTML source code using Markdown -- just paste
522
+ it and indent it, and Markdown will handle the hassle of encoding the
523
+ ampersands and angle brackets. For example, this:</p>
524
+
525
+ <pre><code> &lt;div class="footer"&gt;
526
+ &amp;copy; 2004 Foo Corporation
527
+ &lt;/div&gt;
528
+ </code></pre>
529
+
530
+ <p>will turn into:</p>
531
+
532
+ <pre><code>&lt;pre&gt;&lt;code&gt;&amp;lt;div class="footer"&amp;gt;
533
+ &amp;amp;copy; 2004 Foo Corporation
534
+ &amp;lt;/div&amp;gt;
535
+ &lt;/code&gt;&lt;/pre&gt;
536
+ </code></pre>
537
+
538
+ <p>Regular Markdown syntax is not processed within code blocks. E.g.,
539
+ asterisks are just literal asterisks within a code block. This means
540
+ it's also easy to use Markdown to write about Markdown's own syntax.</p>
541
+
542
+ <h3 id="hr">Horizontal Rules</h3>
543
+
544
+ <p>You can produce a horizontal rule tag (<code>&lt;hr /&gt;</code>) by placing three or
545
+ more hyphens, asterisks, or underscores on a line by themselves. If you
546
+ wish, you may use spaces between the hyphens or asterisks. Each of the
547
+ following lines will produce a horizontal rule:</p>
548
+
549
+ <pre><code>* * *
550
+
551
+ ***
552
+
553
+ *****
554
+
555
+ - - -
556
+
557
+ ---------------------------------------
558
+
559
+ _ _ _
560
+ </code></pre>
561
+
562
+ <hr />
563
+
564
+ <h2 id="span">Span Elements</h2>
565
+
566
+ <h3 id="link">Links</h3>
567
+
568
+ <p>Markdown supports two style of links: <em>inline</em> and <em>reference</em>.</p>
569
+
570
+ <p>In both styles, the link text is delimited by [square brackets].</p>
571
+
572
+ <p>To create an inline link, use a set of regular parentheses immediately
573
+ after the link text's closing square bracket. Inside the parentheses,
574
+ put the URL where you want the link to point, along with an <em>optional</em>
575
+ title for the link, surrounded in quotes. For example:</p>
576
+
577
+ <pre><code>This is [an example](http://example.com/ "Title") inline link.
578
+
579
+ [This link](http://example.net/) has no title attribute.
580
+ </code></pre>
581
+
582
+ <p>Will produce:</p>
583
+
584
+ <pre><code>&lt;p&gt;This is &lt;a href="http://example.com/" title="Title"&gt;
585
+ an example&lt;/a&gt; inline link.&lt;/p&gt;
586
+
587
+ &lt;p&gt;&lt;a href="http://example.net/"&gt;This link&lt;/a&gt; has no
588
+ title attribute.&lt;/p&gt;
589
+ </code></pre>
590
+
591
+ <p>If you're referring to a local resource on the same server, you can
592
+ use relative paths:</p>
593
+
594
+ <pre><code>See my [About](/about/) page for details.
595
+ </code></pre>
596
+
597
+ <p>Reference-style links use a second set of square brackets, inside
598
+ which you place a label of your choosing to identify the link:</p>
599
+
600
+ <pre><code>This is [an example][id] reference-style link.
601
+ </code></pre>
602
+
603
+ <p>You can optionally use a space to separate the sets of brackets:</p>
604
+
605
+ <pre><code>This is [an example] [id] reference-style link.
606
+ </code></pre>
607
+
608
+ <p>Then, anywhere in the document, you define your link label like this,
609
+ on a line by itself:</p>
610
+
611
+ <pre><code>[id]: http://example.com/ "Optional Title Here"
612
+ </code></pre>
613
+
614
+ <p>That is:</p>
615
+
616
+ <ul>
617
+ <li>Square brackets containing the link identifier (optionally
618
+ indented from the left margin using up to three spaces);</li>
619
+ <li>followed by a colon;</li>
620
+ <li>followed by one or more spaces (or tabs);</li>
621
+ <li>followed by the URL for the link;</li>
622
+ <li>optionally followed by a title attribute for the link, enclosed
623
+ in double or single quotes.</li>
624
+ </ul>
625
+
626
+ <p>The link URL may, optionally, be surrounded by angle brackets:</p>
627
+
628
+ <pre><code>[id]: &lt;http://example.com/&gt; "Optional Title Here"
629
+ </code></pre>
630
+
631
+ <p>You can put the title attribute on the next line and use extra spaces
632
+ or tabs for padding, which tends to look better with longer URLs:</p>
633
+
634
+ <pre><code>[id]: http://example.com/longish/path/to/resource/here
635
+ "Optional Title Here"
636
+ </code></pre>
637
+
638
+ <p>Link definitions are only used for creating links during Markdown
639
+ processing, and are stripped from your document in the HTML output.</p>
640
+
641
+ <p>Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are <em>not</em> case sensitive. E.g. these two links:</p>
642
+
643
+ <pre><code>[link text][a]
644
+ [link text][A]
645
+ </code></pre>
646
+
647
+ <p>are equivalent.</p>
648
+
649
+ <p>The <em>implicit link name</em> shortcut allows you to omit the name of the
650
+ link, in which case the link text itself is used as the name.
651
+ Just use an empty set of square brackets -- e.g., to link the word
652
+ "Google" to the google.com web site, you could simply write:</p>
653
+
654
+ <pre><code>[Google][]
655
+ </code></pre>
656
+
657
+ <p>And then define the link:</p>
658
+
659
+ <pre><code>[Google]: http://google.com/
660
+ </code></pre>
661
+
662
+ <p>Because link names may contain spaces, this shortcut even works for
663
+ multiple words in the link text:</p>
664
+
665
+ <pre><code>Visit [Daring Fireball][] for more information.
666
+ </code></pre>
667
+
668
+ <p>And then define the link:</p>
669
+
670
+ <pre><code>[Daring Fireball]: http://daringfireball.net/
671
+ </code></pre>
672
+
673
+ <p>Link definitions can be placed anywhere in your Markdown document. I
674
+ tend to put them immediately after each paragraph in which they're
675
+ used, but if you want, you can put them all at the end of your
676
+ document, sort of like footnotes.</p>
677
+
678
+ <p>Here's an example of reference links in action:</p>
679
+
680
+ <pre><code>I get 10 times more traffic from [Google] [1] than from
681
+ [Yahoo] [2] or [MSN] [3].
682
+
683
+ [1]: http://google.com/ "Google"
684
+ [2]: http://search.yahoo.com/ "Yahoo Search"
685
+ [3]: http://search.msn.com/ "MSN Search"
686
+ </code></pre>
687
+
688
+ <p>Using the implicit link name shortcut, you could instead write:</p>
689
+
690
+ <pre><code>I get 10 times more traffic from [Google][] than from
691
+ [Yahoo][] or [MSN][].
692
+
693
+ [google]: http://google.com/ "Google"
694
+ [yahoo]: http://search.yahoo.com/ "Yahoo Search"
695
+ [msn]: http://search.msn.com/ "MSN Search"
696
+ </code></pre>
697
+
698
+ <p>Both of the above examples will produce the following HTML output:</p>
699
+
700
+ <pre><code>&lt;p&gt;I get 10 times more traffic from &lt;a href="http://google.com/"
701
+ title="Google"&gt;Google&lt;/a&gt; than from
702
+ &lt;a href="http://search.yahoo.com/" title="Yahoo Search"&gt;Yahoo&lt;/a&gt;
703
+ or &lt;a href="http://search.msn.com/" title="MSN Search"&gt;MSN&lt;/a&gt;.&lt;/p&gt;
704
+ </code></pre>
705
+
706
+ <p>For comparison, here is the same paragraph written using
707
+ Markdown's inline link style:</p>
708
+
709
+ <pre><code>I get 10 times more traffic from [Google](http://google.com/ "Google")
710
+ than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
711
+ [MSN](http://search.msn.com/ "MSN Search").
712
+ </code></pre>
713
+
714
+ <p>The point of reference-style links is not that they're easier to
715
+ write. The point is that with reference-style links, your document
716
+ source is vastly more readable. Compare the above examples: using
717
+ reference-style links, the paragraph itself is only 81 characters
718
+ long; with inline-style links, it's 176 characters; and as raw HTML,
719
+ it's 234 characters. In the raw HTML, there's more markup than there
720
+ is text.</p>
721
+
722
+ <p>With Markdown's reference-style links, a source document much more
723
+ closely resembles the final output, as rendered in a browser. By
724
+ allowing you to move the markup-related metadata out of the paragraph,
725
+ you can add links without interrupting the narrative flow of your
726
+ prose.</p>
727
+
728
+ <h3 id="em">Emphasis</h3>
729
+
730
+ <p>Markdown treats asterisks (<code>*</code>) and underscores (<code>_</code>) as indicators of
731
+ emphasis. Text wrapped with one <code>*</code> or <code>_</code> will be wrapped with an
732
+ HTML <code>&lt;em&gt;</code> tag; double <code>*</code>'s or <code>_</code>'s will be wrapped with an HTML
733
+ <code>&lt;strong&gt;</code> tag. E.g., this input:</p>
734
+
735
+ <pre><code>*single asterisks*
736
+
737
+ _single underscores_
738
+
739
+ **double asterisks**
740
+
741
+ __double underscores__
742
+ </code></pre>
743
+
744
+ <p>will produce:</p>
745
+
746
+ <pre><code>&lt;em&gt;single asterisks&lt;/em&gt;
747
+
748
+ &lt;em&gt;single underscores&lt;/em&gt;
749
+
750
+ &lt;strong&gt;double asterisks&lt;/strong&gt;
751
+
752
+ &lt;strong&gt;double underscores&lt;/strong&gt;
753
+ </code></pre>
754
+
755
+ <p>You can use whichever style you prefer; the lone restriction is that
756
+ the same character must be used to open and close an emphasis span.</p>
757
+
758
+ <p>Emphasis can be used in the middle of a word:</p>
759
+
760
+ <pre><code>un*fucking*believable
761
+ </code></pre>
762
+
763
+ <p>But if you surround an <code>*</code> or <code>_</code> with spaces, it'll be treated as a
764
+ literal asterisk or underscore.</p>
765
+
766
+ <p>To produce a literal asterisk or underscore at a position where it
767
+ would otherwise be used as an emphasis delimiter, you can backslash
768
+ escape it:</p>
769
+
770
+ <pre><code>\*this text is surrounded by literal asterisks\*
771
+ </code></pre>
772
+
773
+ <h3 id="code">Code</h3>
774
+
775
+ <p>To indicate a span of code, wrap it with backtick quotes (<code>`</code>).
776
+ Unlike a pre-formatted code block, a code span indicates code within a
777
+ normal paragraph. For example:</p>
778
+
779
+ <pre><code>Use the `printf()` function.
780
+ </code></pre>
781
+
782
+ <p>will produce:</p>
783
+
784
+ <pre><code>&lt;p&gt;Use the &lt;code&gt;printf()&lt;/code&gt; function.&lt;/p&gt;
785
+ </code></pre>
786
+
787
+ <p>To include a literal backtick character within a code span, you can use
788
+ multiple backticks as the opening and closing delimiters:</p>
789
+
790
+ <pre><code>``There is a literal backtick (`) here.``
791
+ </code></pre>
792
+
793
+ <p>which will produce this:</p>
794
+
795
+ <pre><code>&lt;p&gt;&lt;code&gt;There is a literal backtick (`) here.&lt;/code&gt;&lt;/p&gt;
796
+ </code></pre>
797
+
798
+ <p>The backtick delimiters surrounding a code span may include spaces --
799
+ one after the opening, one before the closing. This allows you to place
800
+ literal backtick characters at the beginning or end of a code span:</p>
801
+
802
+ <pre><code>A single backtick in a code span: `` ` ``
803
+
804
+ A backtick-delimited string in a code span: `` `foo` ``
805
+ </code></pre>
806
+
807
+ <p>will produce:</p>
808
+
809
+ <pre><code>&lt;p&gt;A single backtick in a code span: &lt;code&gt;`&lt;/code&gt;&lt;/p&gt;
810
+
811
+ &lt;p&gt;A backtick-delimited string in a code span: &lt;code&gt;`foo`&lt;/code&gt;&lt;/p&gt;
812
+ </code></pre>
813
+
814
+ <p>With a code span, ampersands and angle brackets are encoded as HTML
815
+ entities automatically, which makes it easy to include example HTML
816
+ tags. Markdown will turn this:</p>
817
+
818
+ <pre><code>Please don't use any `&lt;blink&gt;` tags.
819
+ </code></pre>
820
+
821
+ <p>into:</p>
822
+
823
+ <pre><code>&lt;p&gt;Please don't use any &lt;code&gt;&amp;lt;blink&amp;gt;&lt;/code&gt; tags.&lt;/p&gt;
824
+ </code></pre>
825
+
826
+ <p>You can write this:</p>
827
+
828
+ <pre><code>`&amp;#8212;` is the decimal-encoded equivalent of `&amp;mdash;`.
829
+ </code></pre>
830
+
831
+ <p>to produce:</p>
832
+
833
+ <pre><code>&lt;p&gt;&lt;code&gt;&amp;amp;#8212;&lt;/code&gt; is the decimal-encoded
834
+ equivalent of &lt;code&gt;&amp;amp;mdash;&lt;/code&gt;.&lt;/p&gt;
835
+ </code></pre>
836
+
837
+ <h3 id="img">Images</h3>
838
+
839
+ <p>Admittedly, it's fairly difficult to devise a "natural" syntax for
840
+ placing images into a plain text document format.</p>
841
+
842
+ <p>Markdown uses an image syntax that is intended to resemble the syntax
843
+ for links, allowing for two styles: <em>inline</em> and <em>reference</em>.</p>
844
+
845
+ <p>Inline image syntax looks like this:</p>
846
+
847
+ <pre><code>![Alt text](/path/to/img.jpg)
848
+
849
+ ![Alt text](/path/to/img.jpg "Optional title")
850
+ </code></pre>
851
+
852
+ <p>That is:</p>
853
+
854
+ <ul>
855
+ <li>An exclamation mark: <code>!</code>;</li>
856
+ <li>followed by a set of square brackets, containing the <code>alt</code>
857
+ attribute text for the image;</li>
858
+ <li>followed by a set of parentheses, containing the URL or path to
859
+ the image, and an optional <code>title</code> attribute enclosed in double
860
+ or single quotes.</li>
861
+ </ul>
862
+
863
+ <p>Reference-style image syntax looks like this:</p>
864
+
865
+ <pre><code>![Alt text][id]
866
+ </code></pre>
867
+
868
+ <p>Where "id" is the name of a defined image reference. Image references
869
+ are defined using syntax identical to link references:</p>
870
+
871
+ <pre><code>[id]: url/to/image "Optional title attribute"
872
+ </code></pre>
873
+
874
+ <p>As of this writing, Markdown has no syntax for specifying the
875
+ dimensions of an image; if this is important to you, you can simply
876
+ use regular HTML <code>&lt;img&gt;</code> tags.</p>
877
+
878
+ <hr />
879
+
880
+ <h2 id="misc">Miscellaneous</h2>
881
+
882
+ <h3 id="autolink">Automatic Links</h3>
883
+
884
+ <p>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:</p>
885
+
886
+ <pre><code>&lt;http://example.com/&gt;
887
+ </code></pre>
888
+
889
+ <p>Markdown will turn this into:</p>
890
+
891
+ <pre><code>&lt;a href="http://example.com/"&gt;http://example.com/&lt;/a&gt;
892
+ </code></pre>
893
+
894
+ <p>Automatic links for email addresses work similarly, except that
895
+ Markdown will also perform a bit of randomized decimal and hex
896
+ entity-encoding to help obscure your address from address-harvesting
897
+ spambots. For example, Markdown will turn this:</p>
898
+
899
+ <pre><code>&lt;address@example.com&gt;
900
+ </code></pre>
901
+
902
+ <p>into something like this:</p>
903
+
904
+ <pre><code>&lt;a href="&amp;#x6D;&amp;#x61;i&amp;#x6C;&amp;#x74;&amp;#x6F;:&amp;#x61;&amp;#x64;&amp;#x64;&amp;#x72;&amp;#x65;
905
+ &amp;#115;&amp;#115;&amp;#64;&amp;#101;&amp;#120;&amp;#x61;&amp;#109;&amp;#x70;&amp;#x6C;e&amp;#x2E;&amp;#99;&amp;#111;
906
+ &amp;#109;"&gt;&amp;#x61;&amp;#x64;&amp;#x64;&amp;#x72;&amp;#x65;&amp;#115;&amp;#115;&amp;#64;&amp;#101;&amp;#120;&amp;#x61;
907
+ &amp;#109;&amp;#x70;&amp;#x6C;e&amp;#x2E;&amp;#99;&amp;#111;&amp;#109;&lt;/a&gt;
908
+ </code></pre>
909
+
910
+ <p>which will render in a browser as a clickable link to "address@example.com".</p>
911
+
912
+ <p>(This sort of entity-encoding trick will indeed fool many, if not
913
+ most, address-harvesting bots, but it definitely won't fool all of
914
+ them. It's better than nothing, but an address published in this way
915
+ will probably eventually start receiving spam.)</p>
916
+
917
+ <h3 id="backslash">Backslash Escapes</h3>
918
+
919
+ <p>Markdown allows you to use backslash escapes to generate literal
920
+ characters which would otherwise have special meaning in Markdown's
921
+ formatting syntax. For example, if you wanted to surround a word with
922
+ literal asterisks (instead of an HTML <code>&lt;em&gt;</code> tag), you can backslashes
923
+ before the asterisks, like this:</p>
924
+
925
+ <pre><code>\*literal asterisks\*
926
+ </code></pre>
927
+
928
+ <p>Markdown provides backslash escapes for the following characters:</p>
929
+
930
+ <pre><code>\ backslash
931
+ ` backtick
932
+ * asterisk
933
+ _ underscore
934
+ {} curly braces
935
+ [] square brackets
936
+ () parentheses
937
+ # hash mark
938
+ + plus sign
939
+ - minus sign (hyphen)
940
+ . dot
941
+ ! exclamation mark
942
+ </code></pre>