pages/Help.md

   1 ---
   2 layout: page
   3 date: 'Sat 2012-06-09 15:19:14 +0800'
   4 slug: 'Help'
   5 title: "写作说明"
   6 description: ""
   7 ---
   8 {% include JB/setup %}
   9
  10 基于jekyll的东西写起来比较麻烦，得记CLI，是以留档自用。
  11
  12 <ul>
  13     <li><a href="#jekyll_quick_start">Jekyll Quick Start</a></li>
  14     <li><a href="#markdown">On Markdown</a></li>
  15     <li><a href="/pages/HelpLiquid.html">On Liquid</a></li>
  16 </ul>
  17
  18 Jekyll Quick Start
  19 ==================
  20
  21 http://jekyllbootstrap.com/usage/jekyll-quick-start.html
  22
  23 ## Preview
  24
  25         jekyll --server
  26
  27 ## Create a Post
  28
  29         $ rake post title="Hello World"
  30
  31 ## Create a Page
  32
  33         $ rake page name="about.md"
  34         $ rake page name="pages/about.md"   # a nested page
  35         $ rake page name="pages/about"   # a page with a “pretty” path
  36         # this will create the file: ./pages/about/index.html
  37
  38 * * *
  39
  40 Markdown
  41 ========
  42
  43 <ul id="ProjectSubmenu">
  44     <li><a href="http://daringfireball.net/projects/markdown/" title="Markdown Project Page">Markdown Main @ daringfireball.net</a></li>
  45     <li><a href="#syntax_cheatsheet" title="Markdown Syntax Cheatsheet">Markdown Cheatsheet</a></li>
  46     <li><a href="#markdown_basics" title="Markdown Basics">Markdown Basics</a></li>
  47     <li><a href="#markdown_syntax" title="Markdown Syntax Documentation">Markdown Syntax</a></li>
  48     <li><a href="http://daringfireball.net/projects/markdown/dingus" title="Online Markdown Web Form">Dingus @ daringfireball.net</a></li>
  49 </ul>
  50
  51 ### Movable Type ###
  52
  53 You need to use a special `MTMarkdownOptions` container tag in each
  54 Movable Type template where you want HTML 4-style output:
  55
  56     <MTMarkdownOptions output='html4'>
  57         ... put your entry content here ...
  58     </MTMarkdownOptions>
  59
  60 The easiest way to use MTMarkdownOptions is probably to put the
  61 opening tag right after your `<body>` tag, and the closing tag right
  62 before `</body>`.
  63
  64 To suppress Markdown processing in a particular template, i.e. to
  65 publish the raw Markdown-formatted text without translation into
  66 (X)HTML, set the `output` attribute to 'raw':
  67
  68     <MTMarkdownOptions output='raw'>
  69         ... put your entry content here ...
  70     </MTMarkdownOptions>
  71
  72 * * *
  73
  74 ## Syntax Cheatsheet: ##
  75
  76 ### Phrase Emphasis ###
  77
  78         *italic*   **bold**
  79         _italic_   __bold__
  80
  81
  82 ### Links ###
  83
  84 Inline:
  85
  86         An [example](http://url.com/ "Title")
  87
  88 Reference-style labels (titles are optional):
  89
  90         An [example][id]. Then, anywhere
  91         else in the doc, define the link:
  92
  93           [id]: http://example.com/  "Title"
  94
  95
  96
  97 ### Images ###
  98
  99 Inline (titles are optional):
 100
 101         ![alt text](/path/img.jpg "Title")
 102
 103 Reference-style:
 104
 105         ![alt text][id]
 106
 107         [id]: /url/to/img.jpg "Title"
 108
 109
 110 ### Headers ###
 111
 112 Setext-style:
 113
 114         Header 1
 115         ========
 116
 117         Header 2
 118         --------
 119
 120 atx-style (closing #'s are optional):
 121
 122         # Header 1 #
 123
 124         ## Header 2 ##
 125
 126         ###### Header 6
 127
 128
 129 ### Lists ###
 130
 131 Ordered, without paragraphs:
 132
 133         1.  Foo
 134         2.  Bar
 135
 136 Unordered, with paragraphs:
 137
 138         *   A list item.
 139
 140                 With multiple paragraphs.
 141
 142         *   Bar
 143
 144 You can nest them:
 145
 146         *   Abacus
 147                 * answer
 148         *   Bubbles
 149                 1.  bunk
 150                 2.  bupkis
 151                         * BELITTLER
 152                 3. burper
 153         *   Cunning
 154
 155
 156 ### Blockquotes ###
 157
 158         > Email-style angle brackets
 159         > are used for blockquotes.
 160
 161         > > And, they can be nested.
 162
 163         > #### Headers in blockquotes
 164         >
 165         > * You can quote a list.
 166         > * Etc.
 167
 168
 169 ### Code Spans ###
 170
 171         `<code>` spans are delimited
 172         by backticks.
 173
 174         You can include literal backticks
 175         like `` `this` ``.
 176
 177
 178 ### Preformatted Code Blocks ###
 179
 180 Indent every line of a code block by at least 4 spaces or 1 tab.
 181
 182         This is a normal paragraph.
 183
 184             This is a preformatted
 185             code block.
 186
 187
 188 ### Horizontal Rules ###
 189
 190 Three or more dashes or asterisks:
 191
 192         ---
 193
 194         * * *
 195
 196         - - - -
 197
 198
 199 ### Manual Line Breaks ###
 200
 201 End a line with two or more spaces:
 202
 203         Roses are red,
 204         Violets are blue.
 205
 206 * * *
 207
 208 Markdown: Basics
 209 ================
 210
 211 Getting the Gist of Markdown's Formatting Syntax
 212 ------------------------------------------------
 213
 214 This page offers a brief overview of what it's like to use Markdown.
 215 The [syntax page] [s] provides complete, detailed documentation for
 216 every feature, but Markdown should be very easy to pick up simply by
 217 looking at a few examples of it in action. The examples on this page
 218 are written in a before/after style, showing example syntax and the
 219 HTML output produced by Markdown.
 220
 221 It's also helpful to simply try Markdown out; the [Dingus] [d] is a
 222 web application that allows you type your own Markdown-formatted text
 223 and translate it to XHTML.
 224
 225 **Note:** This document is itself written using Markdown; you
 226 can [see the source for it by adding '.text' to the URL] [src].
 227
 228   [s]: /projects/markdown/syntax  "Markdown Syntax"
 229   [d]: /projects/markdown/dingus  "Markdown Dingus"
 230   [src]: http://daringfireball.net/projects/markdown/basics.text
 231
 232
 233 ## Paragraphs, Headers, Blockquotes ##
 234
 235 A paragraph is simply one or more consecutive lines of text, separated
 236 by one or more blank lines. (A blank line is any line that looks like
 237 a blank line -- a line containing nothing but spaces or tabs is
 238 considered blank.) Normal paragraphs should not be indented with
 239 spaces or tabs.
 240
 241 Markdown offers two styles of headers: *Setext* and *atx*.
 242 Setext-style headers for `<h1>` and `<h2>` are created by
 243 "underlining" with equal signs (`=`) and hyphens (`-`), respectively.
 244 To create an atx-style header, you put 1-6 hash marks (`#`) at the
 245 beginning of the line -- the number of hashes equals the resulting
 246 HTML header level.
 247
 248 Blockquotes are indicated using email-style '`>`' angle brackets.
 249
 250 Markdown:
 251
 252     A First Level Header
 253     ====================
 254
 255     A Second Level Header
 256     ---------------------
 257
 258     Now is the time for all good men to come to
 259     the aid of their country. This is just a
 260     regular paragraph.
 261
 262     The quick brown fox jumped over the lazy
 263     dog's back.
 264
 265     ### Header 3
 266
 267     > This is a blockquote.
 268     >
 269     > This is the second paragraph in the blockquote.
 270     >
 271     > ## This is an H2 in a blockquote
 272
 273
 274 Output:
 275
 276     <h1>A First Level Header</h1>
 277
 278     <h2>A Second Level Header</h2>
 279
 280     <p>Now is the time for all good men to come to
 281     the aid of their country. This is just a
 282     regular paragraph.</p>
 283
 284     <p>The quick brown fox jumped over the lazy
 285     dog's back.</p>
 286
 287     <h3>Header 3</h3>
 288
 289     <blockquote>
 290         <p>This is a blockquote.</p>
 291
 292         <p>This is the second paragraph in the blockquote.</p>
 293
 294         <h2>This is an H2 in a blockquote</h2>
 295     </blockquote>
 296
 297
 298
 299 ### Phrase Emphasis ###
 300
 301 Markdown uses asterisks and underscores to indicate spans of emphasis.
 302
 303 Markdown:
 304
 305     Some of these words *are emphasized*.
 306     Some of these words _are emphasized also_.
 307
 308     Use two asterisks for **strong emphasis**.
 309     Or, if you prefer, __use two underscores instead__.
 310
 311 Output:
 312
 313     <p>Some of these words <em>are emphasized</em>.
 314     Some of these words <em>are emphasized also</em>.</p>
 315
 316     <p>Use two asterisks for <strong>strong emphasis</strong>.
 317     Or, if you prefer, <strong>use two underscores instead</strong>.</p>
 318
 319
 320
 321 ## Lists ##
 322
 323 Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
 324 `+`, and `-`) as list markers. These three markers are
 325 interchangable; this:
 326
 327     *   Candy.
 328     *   Gum.
 329     *   Booze.
 330
 331 this:
 332
 333     +   Candy.
 334     +   Gum.
 335     +   Booze.
 336
 337 and this:
 338
 339     -   Candy.
 340     -   Gum.
 341     -   Booze.
 342
 343 all produce the same output:
 344
 345     <ul>
 346     <li>Candy.</li>
 347     <li>Gum.</li>
 348     <li>Booze.</li>
 349     </ul>
 350
 351 Ordered (numbered) lists use regular numbers, followed by periods, as
 352 list markers:
 353
 354     1.  Red
 355     2.  Green
 356     3.  Blue
 357
 358 Output:
 359
 360     <ol>
 361     <li>Red</li>
 362     <li>Green</li>
 363     <li>Blue</li>
 364     </ol>
 365
 366 If you put blank lines between items, you'll get `<p>` tags for the
 367 list item text. You can create multi-paragraph list items by indenting
 368 the paragraphs by 4 spaces or 1 tab:
 369
 370     *   A list item.
 371
 372         With multiple paragraphs.
 373
 374     *   Another item in the list.
 375
 376 Output:
 377
 378     <ul>
 379     <li><p>A list item.</p>
 380     <p>With multiple paragraphs.</p></li>
 381     <li><p>Another item in the list.</p></li>
 382     </ul>
 383
 384
 385
 386 ### Links ###
 387
 388 Markdown supports two styles for creating links: *inline* and
 389 *reference*. With both styles, you use square brackets to delimit the
 390 text you want to turn into a link.
 391
 392 Inline-style links use parentheses immediately after the link text.
 393 For example:
 394
 395     This is an [example link](http://example.com/).
 396
 397 Output:
 398
 399     <p>This is an <a href="http://example.com/">
 400     example link</a>.</p>
 401
 402 Optionally, you may include a title attribute in the parentheses:
 403
 404     This is an [example link](http://example.com/ "With a Title").
 405
 406 Output:
 407
 408     <p>This is an <a href="http://example.com/" title="With a Title">
 409     example link</a>.</p>
 410
 411 Reference-style links allow you to refer to your links by names, which
 412 you define elsewhere in your document:
 413
 414     I get 10 times more traffic from [Google][1] than from
 415     [Yahoo][2] or [MSN][3].
 416
 417     [1]: http://google.com/        "Google"
 418     [2]: http://search.yahoo.com/  "Yahoo Search"
 419     [3]: http://search.msn.com/    "MSN Search"
 420
 421 Output:
 422
 423     <p>I get 10 times more traffic from <a href="http://google.com/"
 424     title="Google">Google</a> than from <a href="http://search.yahoo.com/"
 425     title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
 426     title="MSN Search">MSN</a>.</p>
 427
 428 The title attribute is optional. Link names may contain letters,
 429 numbers and spaces, but are *not* case sensitive:
 430
 431     I start my morning with a cup of coffee and
 432     [The New York Times][NY Times].
 433
 434     [ny times]: http://www.nytimes.com/
 435
 436 Output:
 437
 438     <p>I start my morning with a cup of coffee and
 439     <a href="http://www.nytimes.com/">The New York Times</a>.</p>
 440
 441
 442 ### Images ###
 443
 444 Image syntax is very much like link syntax.
 445
 446 Inline (titles are optional):
 447
 448     ![alt text](/path/to/img.jpg "Title")
 449
 450 Reference-style:
 451
 452     ![alt text][id]
 453
 454     [id]: /path/to/img.jpg "Title"
 455
 456 Both of the above examples produce the same output:
 457
 458     <img src="/path/to/img.jpg" alt="alt text" title="Title" />
 459
 460
 461
 462 ### Code ###
 463
 464 In a regular paragraph, you can create code span by wrapping text in
 465 backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
 466 `>`) will automatically be translated into HTML entities. This makes
 467 it easy to use Markdown to write about HTML example code:
 468
 469     I strongly recommend against using any `<blink>` tags.
 470
 471     I wish SmartyPants used named entities like `&mdash;`
 472     instead of decimal-encoded entites like `&#8212;`.
 473
 474 Output:
 475
 476     <p>I strongly recommend against using any
 477     <code>&lt;blink&gt;</code> tags.</p>
 478
 479     <p>I wish SmartyPants used named entities like
 480     <code>&amp;mdash;</code> instead of decimal-encoded
 481     entites like <code>&amp;#8212;</code>.</p>
 482
 483
 484 To specify an entire block of pre-formatted code, indent every line of
 485 the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
 486 and `>` characters will be escaped automatically.
 487
 488 Markdown:
 489
 490     If you want your page to validate under XHTML 1.0 Strict,
 491     you've got to put paragraph tags in your blockquotes:
 492
 493         <blockquote>
 494             <p>For example.</p>
 495         </blockquote>
 496
 497 Output:
 498
 499     <p>If you want your page to validate under XHTML 1.0 Strict,
 500     you've got to put paragraph tags in your blockquotes:</p>
 501
 502     <pre><code>&lt;blockquote&gt;
 503         &lt;p&gt;For example.&lt;/p&gt;
 504     &lt;/blockquote&gt;
 505     </code></pre>
 506
 507 * * *
 508
 509 Markdown: Syntax
 510 ================
 511
 512 *   [Overview](#overview)
 513     *   [Philosophy](#philosophy)
 514     *   [Inline HTML](#html)
 515     *   [Automatic Escaping for Special Characters](#autoescape)
 516 *   [Block Elements](#block)
 517     *   [Paragraphs and Line Breaks](#p)
 518     *   [Headers](#header)
 519     *   [Blockquotes](#blockquote)
 520     *   [Lists](#list)
 521     *   [Code Blocks](#precode)
 522     *   [Horizontal Rules](#hr)
 523 *   [Span Elements](#span)
 524     *   [Links](#link)
 525     *   [Emphasis](#em)
 526     *   [Code](#code)
 527     *   [Images](#img)
 528 *   [Miscellaneous](#misc)
 529     *   [Backslash Escapes](#backslash)
 530     *   [Automatic Links](#autolink)
 531
 532
 533 **Note:** This document is itself written using Markdown; you
 534 can [see the source for it by adding '.text' to the URL][src].
 535
 536   [src]: /projects/markdown/syntax.text
 537
 538 * * *
 539
 540 <h2 id="overview">Overview</h2>
 541
 542 <h3 id="philosophy">Philosophy</h3>
 543
 544 Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
 545
 546 Readability, however, is emphasized above all else. A Markdown-formatted
 547 document should be publishable as-is, as plain text, without looking
 548 like it's been marked up with tags or formatting instructions. While
 549 Markdown's syntax has been influenced by several existing text-to-HTML
 550 filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
 551 [Grutatext] [5], and [EtText] [6] -- the single biggest source of
 552 inspiration for Markdown's syntax is the format of plain text email.
 553
 554   [1]: http://docutils.sourceforge.net/mirror/setext.html
 555   [2]: http://www.aaronsw.com/2002/atx/
 556   [3]: http://textism.com/tools/textile/
 557   [4]: http://docutils.sourceforge.net/rst.html
 558   [5]: http://www.triptico.com/software/grutatxt.html
 559   [6]: http://ettext.taint.org/doc/
 560
 561 To this end, Markdown's syntax is comprised entirely of punctuation
 562 characters, which punctuation characters have been carefully chosen so
 563 as to look like what they mean. E.g., asterisks around a word actually
 564 look like \*emphasis\*. Markdown lists look like, well, lists. Even
 565 blockquotes look like quoted passages of text, assuming you've ever
 566 used email.
 567
 568
 569
 570 <h3 id="html">Inline HTML</h3>
 571
 572 Markdown's syntax is intended for one purpose: to be used as a
 573 format for *writing* for the web.
 574
 575 Markdown is not a replacement for HTML, or even close to it. Its
 576 syntax is very small, corresponding only to a very small subset of
 577 HTML tags. The idea is *not* to create a syntax that makes it easier
 578 to insert HTML tags. In my opinion, HTML tags are already easy to
 579 insert. The idea for Markdown is to make it easy to read, write, and
 580 edit prose. HTML is a *publishing* format; Markdown is a *writing*
 581 format. Thus, Markdown's formatting syntax only addresses issues that
 582 can be conveyed in plain text.
 583
 584 For any markup that is not covered by Markdown's syntax, you simply
 585 use HTML itself. There's no need to preface it or delimit it to
 586 indicate that you're switching from Markdown to HTML; you just use
 587 the tags.
 588
 589 The only restrictions are that block-level HTML elements -- e.g. `<div>`,
 590 `<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
 591 content by blank lines, and the start and end tags of the block should
 592 not be indented with tabs or spaces. Markdown is smart enough not
 593 to add extra (unwanted) `<p>` tags around HTML block-level tags.
 594
 595 For example, to add an HTML table to a Markdown article:
 596
 597     This is a regular paragraph.
 598
 599     <table>
 600         <tr>
 601             <td>Foo</td>
 602         </tr>
 603     </table>
 604
 605     This is another regular paragraph.
 606
 607 Note that Markdown formatting syntax is not processed within block-level
 608 HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
 609 HTML block.
 610
 611 Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
 612 used anywhere in a Markdown paragraph, list item, or header. If you
 613 want, you can even use HTML tags instead of Markdown formatting; e.g. if
 614 you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
 615 link or image syntax, go right ahead.
 616
 617 Unlike block-level HTML tags, Markdown syntax *is* processed within
 618 span-level tags.
 619
 620
 621 <h3 id="autoescape">Automatic Escaping for Special Characters</h3>
 622
 623 In HTML, there are two characters that demand special treatment: `<`
 624 and `&`. Left angle brackets are used to start tags; ampersands are
 625 used to denote HTML entities. If you want to use them as literal
 626 characters, you must escape them as entities, e.g. `&lt;`, and
 627 `&amp;`.
 628
 629 Ampersands in particular are bedeviling for web writers. If you want to
 630 write about 'AT&T', you need to write '`AT&amp;T`'. You even need to
 631 escape ampersands within URLs. Thus, if you want to link to:
 632
 633     http://images.google.com/images?num=30&q=larry+bird
 634
 635 you need to encode the URL as:
 636
 637     http://images.google.com/images?num=30&amp;q=larry+bird
 638
 639 in your anchor tag `href` attribute. Needless to say, this is easy to
 640 forget, and is probably the single most common source of HTML validation
 641 errors in otherwise well-marked-up web sites.
 642
 643 Markdown allows you to use these characters naturally, taking care of
 644 all the necessary escaping for you. If you use an ampersand as part of
 645 an HTML entity, it remains unchanged; otherwise it will be translated
 646 into `&amp;`.
 647
 648 So, if you want to include a copyright symbol in your article, you can write:
 649
 650     &copy;
 651
 652 and Markdown will leave it alone. But if you write:
 653
 654     AT&T
 655
 656 Markdown will translate it to:
 657
 658     AT&amp;T
 659
 660 Similarly, because Markdown supports [inline HTML](#html), if you use
 661 angle brackets as delimiters for HTML tags, Markdown will treat them as
 662 such. But if you write:
 663
 664     4 < 5
 665
 666 Markdown will translate it to:
 667
 668     4 &lt; 5
 669
 670 However, inside Markdown code spans and blocks, angle brackets and
 671 ampersands are *always* encoded automatically. This makes it easy to use
 672 Markdown to write about HTML code. (As opposed to raw HTML, which is a
 673 terrible format for writing about HTML syntax, because every single `<`
 674 and `&` in your example code needs to be escaped.)
 675
 676
 677 * * *
 678
 679
 680 <h2 id="block">Block Elements</h2>
 681
 682
 683 <h3 id="p">Paragraphs and Line Breaks</h3>
 684
 685 A paragraph is simply one or more consecutive lines of text, separated
 686 by one or more blank lines. (A blank line is any line that looks like a
 687 blank line -- a line containing nothing but spaces or tabs is considered
 688 blank.) Normal paragraphs should not be indented with spaces or tabs.
 689
 690 The implication of the "one or more consecutive lines of text" rule is
 691 that Markdown supports "hard-wrapped" text paragraphs. This differs
 692 significantly from most other text-to-HTML formatters (including Movable
 693 Type's "Convert Line Breaks" option) which translate every line break
 694 character in a paragraph into a `<br />` tag.
 695
 696 When you *do* want to insert a `<br />` break tag using Markdown, you
 697 end a line with two or more spaces, then type return.
 698
 699 Yes, this takes a tad more effort to create a `<br />`, but a simplistic
 700 "every line break is a `<br />`" rule wouldn't work for Markdown.
 701 Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
 702 work best -- and look better -- when you format them with hard breaks.
 703
 704   [bq]: #blockquote
 705   [l]:  #list
 706
 707
 708
 709 <h3 id="header">Headers</h3>
 710
 711 Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
 712
 713 Setext-style headers are "underlined" using equal signs (for first-level
 714 headers) and dashes (for second-level headers). For example:
 715
 716     This is an H1
 717     =============
 718
 719     This is an H2
 720     -------------
 721
 722 Any number of underlining `=`'s or `-`'s will work.
 723
 724 Atx-style headers use 1-6 hash characters at the start of the line,
 725 corresponding to header levels 1-6. For example:
 726
 727     # This is an H1
 728
 729     ## This is an H2
 730
 731     ###### This is an H6
 732
 733 Optionally, you may "close" atx-style headers. This is purely
 734 cosmetic -- you can use this if you think it looks better. The
 735 closing hashes don't even need to match the number of hashes
 736 used to open the header. (The number of opening hashes
 737 determines the header level.) :
 738
 739     # This is an H1 #
 740
 741     ## This is an H2 ##
 742
 743     ### This is an H3 ######
 744
 745
 746 <h3 id="blockquote">Blockquotes</h3>
 747
 748 Markdown uses email-style `>` characters for blockquoting. If you're
 749 familiar with quoting passages of text in an email message, then you
 750 know how to create a blockquote in Markdown. It looks best if you hard
 751 wrap the text and put a `>` before every line:
 752
 753     > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
 754     > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
 755     > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
 756     >
 757     > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
 758     > id sem consectetuer libero luctus adipiscing.
 759
 760 Markdown allows you to be lazy and only put the `>` before the first
 761 line of a hard-wrapped paragraph:
 762
 763     > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
 764     consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
 765     Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
 766
 767     > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
 768     id sem consectetuer libero luctus adipiscing.
 769
 770 Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
 771 adding additional levels of `>`:
 772
 773     > This is the first level of quoting.
 774     >
 775     > > This is nested blockquote.
 776     >
 777     > Back to the first level.
 778
 779 Blockquotes can contain other Markdown elements, including headers, lists,
 780 and code blocks:
 781
 782         > ## This is a header.
 783         >
 784         > 1.   This is the first list item.
 785         > 2.   This is the second list item.
 786         >
 787         > Here's some example code:
 788         >
 789         >     return shell_exec("echo $input | $markdown_script");
 790
 791 Any decent text editor should make email-style quoting easy. For
 792 example, with BBEdit, you can make a selection and choose Increase
 793 Quote Level from the Text menu.
 794
 795
 796 <h3 id="list">Lists</h3>
 797
 798 Markdown supports ordered (numbered) and unordered (bulleted) lists.
 799
 800 Unordered lists use asterisks, pluses, and hyphens -- interchangably
 801 -- as list markers:
 802
 803     *   Red
 804     *   Green
 805     *   Blue
 806
 807 is equivalent to:
 808
 809     +   Red
 810     +   Green
 811     +   Blue
 812
 813 and:
 814
 815     -   Red
 816     -   Green
 817     -   Blue
 818
 819 Ordered lists use numbers followed by periods:
 820
 821     1.  Bird
 822     2.  McHale
 823     3.  Parish
 824
 825 It's important to note that the actual numbers you use to mark the
 826 list have no effect on the HTML output Markdown produces. The HTML
 827 Markdown produces from the above list is:
 828
 829     <ol>
 830     <li>Bird</li>
 831     <li>McHale</li>
 832     <li>Parish</li>
 833     </ol>
 834
 835 If you instead wrote the list in Markdown like this:
 836
 837     1.  Bird
 838     1.  McHale
 839     1.  Parish
 840
 841 or even:
 842
 843     3. Bird
 844     1. McHale
 845     8. Parish
 846
 847 you'd get the exact same HTML output. The point is, if you want to,
 848 you can use ordinal numbers in your ordered Markdown lists, so that
 849 the numbers in your source match the numbers in your published HTML.
 850 But if you want to be lazy, you don't have to.
 851
 852 If you do use lazy list numbering, however, you should still start the
 853 list with the number 1. At some point in the future, Markdown may support
 854 starting ordered lists at an arbitrary number.
 855
 856 List markers typically start at the left margin, but may be indented by
 857 up to three spaces. List markers must be followed by one or more spaces
 858 or a tab.
 859
 860 To make lists look nice, you can wrap items with hanging indents:
 861
 862     *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
 863         Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
 864         viverra nec, fringilla in, laoreet vitae, risus.
 865     *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
 866         Suspendisse id sem consectetuer libero luctus adipiscing.
 867
 868 But if you want to be lazy, you don't have to:
 869
 870     *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
 871     Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
 872     viverra nec, fringilla in, laoreet vitae, risus.
 873     *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
 874     Suspendisse id sem consectetuer libero luctus adipiscing.
 875
 876 If list items are separated by blank lines, Markdown will wrap the
 877 items in `<p>` tags in the HTML output. For example, this input:
 878
 879     *   Bird
 880     *   Magic
 881
 882 will turn into:
 883
 884     <ul>
 885     <li>Bird</li>
 886     <li>Magic</li>
 887     </ul>
 888
 889 But this:
 890
 891     *   Bird
 892
 893     *   Magic
 894
 895 will turn into:
 896
 897     <ul>
 898     <li><p>Bird</p></li>
 899     <li><p>Magic</p></li>
 900     </ul>
 901
 902 List items may consist of multiple paragraphs. Each subsequent
 903 paragraph in a list item must be indented by either 4 spaces
 904 or one tab:
 905
 906     1.  This is a list item with two paragraphs. Lorem ipsum dolor
 907         sit amet, consectetuer adipiscing elit. Aliquam hendrerit
 908         mi posuere lectus.
 909
 910         Vestibulum enim wisi, viverra nec, fringilla in, laoreet
 911         vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
 912         sit amet velit.
 913
 914     2.  Suspendisse id sem consectetuer libero luctus adipiscing.
 915
 916 It looks nice if you indent every line of the subsequent
 917 paragraphs, but here again, Markdown will allow you to be
 918 lazy:
 919
 920     *   This is a list item with two paragraphs.
 921
 922         This is the second paragraph in the list item. You're
 923     only required to indent the first line. Lorem ipsum dolor
 924     sit amet, consectetuer adipiscing elit.
 925
 926     *   Another item in the same list.
 927
 928 To put a blockquote within a list item, the blockquote's `>`
 929 delimiters need to be indented:
 930
 931     *   A list item with a blockquote:
 932
 933         > This is a blockquote
 934         > inside a list item.
 935
 936 To put a code block within a list item, the code block needs
 937 to be indented *twice* -- 8 spaces or two tabs:
 938
 939     *   A list item with a code block:
 940
 941             <code goes here>
 942
 943
 944 It's worth noting that it's possible to trigger an ordered list by
 945 accident, by writing something like this:
 946
 947     1986. What a great season.
 948
 949 In other words, a *number-period-space* sequence at the beginning of a
 950 line. To avoid this, you can backslash-escape the period:
 951
 952     1986\. What a great season.
 953
 954
 955
 956 <h3 id="precode">Code Blocks</h3>
 957
 958 Pre-formatted code blocks are used for writing about programming or
 959 markup source code. Rather than forming normal paragraphs, the lines
 960 of a code block are interpreted literally. Markdown wraps a code block
 961 in both `<pre>` and `<code>` tags.
 962
 963 To produce a code block in Markdown, simply indent every line of the
 964 block by at least 4 spaces or 1 tab. For example, given this input:
 965
 966     This is a normal paragraph:
 967
 968         This is a code block.
 969
 970 Markdown will generate:
 971
 972     <p>This is a normal paragraph:</p>
 973
 974     <pre><code>This is a code block.
 975     </code></pre>
 976
 977 One level of indentation -- 4 spaces or 1 tab -- is removed from each
 978 line of the code block. For example, this:
 979
 980     Here is an example of AppleScript:
 981
 982         tell application "Foo"
 983             beep
 984         end tell
 985
 986 will turn into:
 987
 988     <p>Here is an example of AppleScript:</p>
 989
 990     <pre><code>tell application "Foo"
 991         beep
 992     end tell
 993     </code></pre>
 994
 995 A code block continues until it reaches a line that is not indented
 996 (or the end of the article).
 997
 998 Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
 999 are automatically converted into HTML entities. This makes it very
1000 easy to include example HTML source code using Markdown -- just paste
1001 it and indent it, and Markdown will handle the hassle of encoding the
1002 ampersands and angle brackets. For example, this:
1003
1004         <div class="footer">
1005             &copy; 2004 Foo Corporation
1006         </div>
1007
1008 will turn into:
1009
1010     <pre><code>&lt;div class="footer"&gt;
1011         &amp;copy; 2004 Foo Corporation
1012     &lt;/div&gt;
1013     </code></pre>
1014
1015 Regular Markdown syntax is not processed within code blocks. E.g.,
1016 asterisks are just literal asterisks within a code block. This means
1017 it's also easy to use Markdown to write about Markdown's own syntax.
1018
1019
1020
1021 <h3 id="hr">Horizontal Rules</h3>
1022
1023 You can produce a horizontal rule tag (`<hr />`) by placing three or
1024 more hyphens, asterisks, or underscores on a line by themselves. If you
1025 wish, you may use spaces between the hyphens or asterisks. Each of the
1026 following lines will produce a horizontal rule:
1027
1028     * * *
1029
1030     ***
1031
1032     *****
1033
1034     - - -
1035
1036     ---------------------------------------
1037
1038
1039 * * *
1040
1041 <h2 id="span">Span Elements</h2>
1042
1043 <h3 id="link">Links</h3>
1044
1045 Markdown supports two style of links: *inline* and *reference*.
1046
1047 In both styles, the link text is delimited by \[square brackets\].
1048
1049 To create an inline link, use a set of regular parentheses immediately
1050 after the link text's closing square bracket. Inside the parentheses,
1051 put the URL where you want the link to point, along with an *optional*
1052 title for the link, surrounded in quotes. For example:
1053
1054     This is [an example](http://example.com/ "Title") inline link.
1055
1056     [This link](http://example.net/) has no title attribute.
1057
1058 Will produce:
1059
1060     <p>This is <a href="http://example.com/" title="Title">
1061     an example</a> inline link.</p>
1062
1063     <p><a href="http://example.net/">This link</a> has no
1064     title attribute.</p>
1065
1066 If you're referring to a local resource on the same server, you can
1067 use relative paths:
1068
1069     See my [About](/about/) page for details.
1070
1071 Reference-style links use a second set of square brackets, inside
1072 which you place a label of your choosing to identify the link:
1073
1074     This is [an example][id] reference-style link.
1075
1076 You can optionally use a space to separate the sets of brackets:
1077
1078     This is [an example] [id] reference-style link.
1079
1080 Then, anywhere in the document, you define your link label like this,
1081 on a line by itself:
1082
1083     [id]: http://example.com/  "Optional Title Here"
1084
1085 That is:
1086
1087 *   Square brackets containing the link identifier (optionally
1088     indented from the left margin using up to three spaces);
1089 *   followed by a colon;
1090 *   followed by one or more spaces (or tabs);
1091 *   followed by the URL for the link;
1092 *   optionally followed by a title attribute for the link, enclosed
1093     in double or single quotes, or enclosed in parentheses.
1094
1095 The following three link definitions are equivalent:
1096
1097         [foo]: http://example.com/  "Optional Title Here"
1098         [foo]: http://example.com/  'Optional Title Here'
1099         [foo]: http://example.com/  (Optional Title Here)
1100
1101 **Note:** There is a known bug in Markdown.pl 1.0.1 which prevents
1102 single quotes from being used to delimit link titles.
1103
1104 The link URL may, optionally, be surrounded by angle brackets:
1105
1106     [id]: <http://example.com/>  "Optional Title Here"
1107
1108 You can put the title attribute on the next line and use extra spaces
1109 or tabs for padding, which tends to look better with longer URLs:
1110
1111     [id]: http://example.com/longish/path/to/resource/here
1112         "Optional Title Here"
1113
1114 Link definitions are only used for creating links during Markdown
1115 processing, and are stripped from your document in the HTML output.
1116
1117 Link definition names may consist of letters, numbers, spaces, and
1118 punctuation -- but they are *not* case sensitive. E.g. these two
1119 links:
1120
1121         [link text][a]
1122         [link text][A]
1123
1124 are equivalent.
1125
1126 The *implicit link name* shortcut allows you to omit the name of the
1127 link, in which case the link text itself is used as the name.
1128 Just use an empty set of square brackets -- e.g., to link the word
1129 "Google" to the google.com web site, you could simply write:
1130
1131         [Google][]
1132
1133 And then define the link:
1134
1135         [Google]: http://google.com/
1136
1137 Because link names may contain spaces, this shortcut even works for
1138 multiple words in the link text:
1139
1140         Visit [Daring Fireball][] for more information.
1141
1142 And then define the link:
1143
1144         [Daring Fireball]: http://daringfireball.net/
1145
1146 Link definitions can be placed anywhere in your Markdown document. I
1147 tend to put them immediately after each paragraph in which they're
1148 used, but if you want, you can put them all at the end of your
1149 document, sort of like footnotes.
1150
1151 Here's an example of reference links in action:
1152
1153     I get 10 times more traffic from [Google] [1] than from
1154     [Yahoo] [2] or [MSN] [3].
1155
1156       [1]: http://google.com/        "Google"
1157       [2]: http://search.yahoo.com/  "Yahoo Search"
1158       [3]: http://search.msn.com/    "MSN Search"
1159
1160 Using the implicit link name shortcut, you could instead write:
1161
1162     I get 10 times more traffic from [Google][] than from
1163     [Yahoo][] or [MSN][].
1164
1165       [google]: http://google.com/        "Google"
1166       [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
1167       [msn]:    http://search.msn.com/    "MSN Search"
1168
1169 Both of the above examples will produce the following HTML output:
1170
1171     <p>I get 10 times more traffic from <a href="http://google.com/"
1172     title="Google">Google</a> than from
1173     <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
1174     or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
1175
1176 For comparison, here is the same paragraph written using
1177 Markdown's inline link style:
1178
1179     I get 10 times more traffic from [Google](http://google.com/ "Google")
1180     than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
1181     [MSN](http://search.msn.com/ "MSN Search").
1182
1183 The point of reference-style links is not that they're easier to
1184 write. The point is that with reference-style links, your document
1185 source is vastly more readable. Compare the above examples: using
1186 reference-style links, the paragraph itself is only 81 characters
1187 long; with inline-style links, it's 176 characters; and as raw HTML,
1188 it's 234 characters. In the raw HTML, there's more markup than there
1189 is text.
1190
1191 With Markdown's reference-style links, a source document much more
1192 closely resembles the final output, as rendered in a browser. By
1193 allowing you to move the markup-related metadata out of the paragraph,
1194 you can add links without interrupting the narrative flow of your
1195 prose.
1196
1197
1198 <h3 id="em">Emphasis</h3>
1199
1200 Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
1201 emphasis. Text wrapped with one `*` or `_` will be wrapped with an
1202 HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
1203 `<strong>` tag. E.g., this input:
1204
1205     *single asterisks*
1206
1207     _single underscores_
1208
1209     **double asterisks**
1210
1211     __double underscores__
1212
1213 will produce:
1214
1215     <em>single asterisks</em>
1216
1217     <em>single underscores</em>
1218
1219     <strong>double asterisks</strong>
1220
1221     <strong>double underscores</strong>
1222
1223 You can use whichever style you prefer; the lone restriction is that
1224 the same character must be used to open and close an emphasis span.
1225
1226 Emphasis can be used in the middle of a word:
1227
1228     un*frigging*believable
1229
1230 But if you surround an `*` or `_` with spaces, it'll be treated as a
1231 literal asterisk or underscore.
1232
1233 To produce a literal asterisk or underscore at a position where it
1234 would otherwise be used as an emphasis delimiter, you can backslash
1235 escape it:
1236
1237     \*this text is surrounded by literal asterisks\*
1238
1239
1240
1241 <h3 id="code">Code</h3>
1242
1243 To indicate a span of code, wrap it with backtick quotes (`` ` ``).
1244 Unlike a pre-formatted code block, a code span indicates code within a
1245 normal paragraph. For example:
1246
1247     Use the `printf()` function.
1248
1249 will produce:
1250
1251     <p>Use the <code>printf()</code> function.</p>
1252
1253 To include a literal backtick character within a code span, you can use
1254 multiple backticks as the opening and closing delimiters:
1255
1256     ``There is a literal backtick (`) here.``
1257
1258 which will produce this:
1259
1260     <p><code>There is a literal backtick (`) here.</code></p>
1261
1262 The backtick delimiters surrounding a code span may include spaces --
1263 one after the opening, one before the closing. This allows you to place
1264 literal backtick characters at the beginning or end of a code span:
1265
1266         A single backtick in a code span: `` ` ``
1267
1268         A backtick-delimited string in a code span: `` `foo` ``
1269
1270 will produce:
1271
1272         <p>A single backtick in a code span: <code>`</code></p>
1273
1274         <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
1275
1276 With a code span, ampersands and angle brackets are encoded as HTML
1277 entities automatically, which makes it easy to include example HTML
1278 tags. Markdown will turn this:
1279
1280     Please don't use any `<blink>` tags.
1281
1282 into:
1283
1284     <p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
1285
1286 You can write this:
1287
1288     `&#8212;` is the decimal-encoded equivalent of `&mdash;`.
1289
1290 to produce:
1291
1292     <p><code>&amp;#8212;</code> is the decimal-encoded
1293     equivalent of <code>&amp;mdash;</code>.</p>
1294
1295
1296
1297 <h3 id="img">Images</h3>
1298
1299 Admittedly, it's fairly difficult to devise a "natural" syntax for
1300 placing images into a plain text document format.
1301
1302 Markdown uses an image syntax that is intended to resemble the syntax
1303 for links, allowing for two styles: *inline* and *reference*.
1304
1305 Inline image syntax looks like this:
1306
1307     ![Alt text](/path/to/img.jpg)
1308
1309     ![Alt text](/path/to/img.jpg "Optional title")
1310
1311 That is:
1312
1313 *   An exclamation mark: `!`;
1314 *   followed by a set of square brackets, containing the `alt`
1315     attribute text for the image;
1316 *   followed by a set of parentheses, containing the URL or path to
1317     the image, and an optional `title` attribute enclosed in double
1318     or single quotes.
1319
1320 Reference-style image syntax looks like this:
1321
1322     ![Alt text][id]
1323
1324 Where "id" is the name of a defined image reference. Image references
1325 are defined using syntax identical to link references:
1326
1327     [id]: url/to/image  "Optional title attribute"
1328
1329 As of this writing, Markdown has no syntax for specifying the
1330 dimensions of an image; if this is important to you, you can simply
1331 use regular HTML `<img>` tags.
1332
1333
1334 * * *
1335
1336
1337 <h2 id="misc">Miscellaneous</h2>
1338
1339 <h3 id="autolink">Automatic Links</h3>
1340
1341 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:
1342
1343     <http://example.com/>
1344
1345 Markdown will turn this into:
1346
1347     <a href="http://example.com/">http://example.com/</a>
1348
1349 Automatic links for email addresses work similarly, except that
1350 Markdown will also perform a bit of randomized decimal and hex
1351 entity-encoding to help obscure your address from address-harvesting
1352 spambots. For example, Markdown will turn this:
1353
1354     <address@example.com>
1355
1356 into something like this:
1357
1358     <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
1359     &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
1360     &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
1361     &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
1362
1363 which will render in a browser as a clickable link to "address@example.com".
1364
1365 (This sort of entity-encoding trick will indeed fool many, if not
1366 most, address-harvesting bots, but it definitely won't fool all of
1367 them. It's better than nothing, but an address published in this way
1368 will probably eventually start receiving spam.)
1369
1370
1371
1372 <h3 id="backslash">Backslash Escapes</h3>
1373
1374 Markdown allows you to use backslash escapes to generate literal
1375 characters which would otherwise have special meaning in Markdown's
1376 formatting syntax. For example, if you wanted to surround a word
1377 with literal asterisks (instead of an HTML `<em>` tag), you can use
1378 backslashes before the asterisks, like this:
1379
1380     \*literal asterisks\*
1381
1382 Markdown provides backslash escapes for the following characters:
1383
1384     \   backslash
1385     `   backtick
1386     *   asterisk
1387     _   underscore
1388     {}  curly braces
1389     []  square brackets
1390     ()  parentheses
1391     #   hash mark
1392         +       plus sign
1393         -       minus sign (hyphen)
1394     .   dot
1395     !   exclamation mark