bower_components/marked/test/tests/markdown_documentation_syntax.html - Issue 786953007: npm_modules: Fork bower_components into Polymer 0.4.0 and 0.5.0 versions

Side by Side Diff: bower_components/marked/test/tests/markdown_documentation_syntax.html

Issue 786953007: npm_modules: Fork bower_components into Polymer 0.4.0 and 0.5.0 versions (Closed) Base URL: https://chromium.googlesource.com/infra/third_party/npm_modules.git@master

Patch Set: Created 5 years, 11 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch

« no previous file with comments | « bower_components/marked/test/tests/markdown_documentation_basics.text ('k') | bower_components/marked/test/tests/markdown_documentation_syntax.text » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')

OLD	NEW
	(Empty)
1 <h1 id="markdown-syntax">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 Informat ion">License</a></li>

8 <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Din gus</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 &#3 9;.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 h ref="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><di v></code>,

87 <code><table></code>, <code><pre></code>, <code><p></code>, et c. -- 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><p></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 <table>

97 <tr>

98 <td>Foo</td>

99 </tr>

100 </table>

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><span></code>, <code><cite></c ode>, or <code><del></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><a></code> or <code><img></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><</ code>

121 and <code>&</code>. Left angle brackets are used to start tags; ampersands a re

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>&lt;</code>, and

124 <code>&amp;</code>.</p>

125

126 <p>Ampersands in particular are bedeviling for web writers. If you want to

127 write about 'AT&T', you need to write '<code>AT&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&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;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;</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>&copy;

150 </code></pre>

151

152 <p>and Markdown will leave it alone. But if you write:</p>

153

154 <pre><code>AT&T

155 </code></pre>

156

157 <p>Markdown will translate it to:</p>

158

159 <pre><code>AT&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 < 5

167 </code></pre>

168

169 <p>Markdown will translate it to:</p>

170

171 <pre><code>4 &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><</ code>

178 and <code>&</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 br eak

195 character in a paragraph into a <code><br /></code> tag.</p>

196

197 <p>When you <em>do</em> want to insert a <code><br /></code> break tag usi ng 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><br /></code>, but a simplistic

201 "every line break is a <code><br /></code>" rule wouldn't wo rk for Markdown.

202 Markdown's email-style <a href="#blockquote">blockquoting</a> and multi-para graph <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 w ork.</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>></code> characters for blockquoting. If y ou'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>></code> before every line:</p>

250

251 <pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,

252 > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

253 > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

254 >

255 > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse

256 > id sem consectetuer libero luctus adipiscing.

257 </code></pre>

258

259 <p>Markdown allows you to be lazy and only put the <code>></code> before the first

260 line of a hard-wrapped paragraph:</p>

261

262 <pre><code>> 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 > 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>></code>:</p>

272

273 <pre><code>> This is the first level of quoting.

274 >

275 > > This is nested blockquote.

276 >

277 > 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>> ## This is a header.

284 >

285 > 1. This is the first list item.

286 > 2. This is the second list item.

287 >

288 > Here's some example code:

289 >

290 > 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><ol>

335 <li>Bird</li>

336 <li>McHale</li>

337 <li>Parish</li>

338 </ol>

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><p></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><ul>

396 <li>Bird</li>

397 <li>Magic</li>

398 </ul>

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><ul>

411 <li><p>Bird</p></li>

412 <li><p>Magic</p></li>

413 </ul>

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>></code >

445 delimiters need to be indented:</p>

446

447 <pre><code>* A list item with a blockquote:

448

449 > This is a blockquote

450 > 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 <code goes here>

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><pre></code> and <code><code></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><p>This is a normal paragraph:</p>

491

492 <pre><code>This is a code block.

493 </code></pre>

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><p>Here is an example of AppleScript:</p>

509

510 <pre><code>tell application "Foo"

511 beep

512 end tell

513 </code></pre>

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>&</code>) and angle brackets (<cod e><</code> and <code>></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> <div class="footer">

526 &copy; 2004 Foo Corporation

527 </div>

528 </code></pre>

529

530 <p>will turn into:</p>

531

532 <pre><code><pre><code>&lt;div class="footer"&gt;

533 &amp;copy; 2004 Foo Corporation

534 &lt;/div&gt;

535 </code></pre>

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><hr></code>) by placing th ree 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 li nk.

578

579 [This link](http://example.net/) has no title attribute.

580 </code></pre>

581

582 <p>Will produce:</p>

583

584 <pre><code><p>This is <a href="http://example.com/" title=&qu ot;Title">

585 an example</a> inline link.</p>

586

587 <p><a href="http://example.net/">This link</a> has n o

588 title attribute.</p>

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]: <http://example.com/> "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 punctuati on -- 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><p>I get 10 times more traffic from <a href="http://goo gle.com/"

701 title="Google">Google</a> than from

702 <a href="http://search.yahoo.com/" title="Yahoo Search"&g t;Yahoo</a>

703 or <a href="http://search.msn.com/" title="MSN Search"&gt ;MSN</a>.</p>

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/ "Go ogle")

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>) a s indicators of

731 emphasis. Text wrapped with one <code>*</code> or <code>_</code> will be wrapped with an

732 HTML <code><em></code> tag; double <code>*</code>'s or <code>_</code>& #39;s will be wrapped with an HTML

733 <code><strong></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><em>single asterisks</em>

747

748 <em>single underscores</em>

749

750 <strong>double asterisks</strong>

751

752 <strong>double underscores</strong>

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>unfuckingbelievable

761 </code></pre>

762

763 <p>But if you surround an <code>*</code> or <code>_</code> with spaces, it'l l 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><p>Use the <code>printf()</code> function.</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><p><code>There is a literal backtick (`) here.</code&g t;</p>

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><p>A single backtick in a code span: <code>`</code> </p>

810

811 <p>A backtick-delimited string in a code span: <code>`foo`</code& gt;</p>

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 `<blink>` tags.

819 </code></pre>

820

821 <p>into:</p>

822

823 <pre><code><p>Please don't use any <code>&lt;blink&gt;&l t;/code> tags.</p>

824 </code></pre>

825

826 <p>You can write this:</p>

827

828 <pre><code>`&#8212;` is the decimal-encoded equivalent of `&mdash;`.

829 </code></pre>

830

831 <p>to produce:</p>

832

833 <pre><code><p><code>&amp;#8212;</code> is the decimal-enco ded

834 equivalent of <code>&amp;mdash;</code>.</p>

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 referenc es

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><img></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 f or 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><http://example.com/>

887 </code></pre>

888

889 <p>Markdown will turn this into:</p>

890

891 <pre><code><a href="http://example.com/">http://example.com/< /a>

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><address@example.com>

900 </code></pre>

901

902 <p>into something like this:</p>

903

904 <pre><code><a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;: &#x61;&#x64;&#x64;&#x72;&#x65;

905 &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;& amp;#x6C;e&#x2E;&#99;&#111;

906 &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115; &#115;&#64;&#101;&#120;&#x61;

907 &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

908 </code></pre>

909

910 <p>which will render in a browser as a clickable link to "address@example.c om".</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><em></code> tag), you can back slashes

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>

OLD	NEW