pubdoc/Markdown-Syntax-CN/basics.text

   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
  39 a blank line -- a line containing nothing but spaces or tabs is
  40 considered blank.) Normal paragraphs should not be indented with
  41 spaces or tabs.
  42
  43 Markdown offers two styles of headers: *Setext* and *atx*.
  44 Setext-style headers for `<h1>` and `<h2>` are created by
  45 "underlining" with equal signs (`=`) and hyphens (`-`), respectively.
  46 To create an atx-style header, you put 1-6 hash marks (`#`) at the
  47 beginning of the line -- the number of hashes equals the resulting
  48 HTML header level.
  49
  50 Blockquotes are indicated using email-style '`>`' angle brackets.
  51
  52 Markdown:
  53
  54     A First Level Header
  55     ====================
  56
  57     A Second Level Header
  58     ---------------------
  59
  60     Now is the time for all good men to come to
  61     the aid of their country. This is just a
  62     regular paragraph.
  63
  64     The quick brown fox jumped over the lazy
  65     dog's back.
  66
  67     ### Header 3
  68
  69     > This is a blockquote.
  70     >
  71     > This is the second paragraph in the blockquote.
  72     >
  73     > ## This is an H2 in a blockquote
  74
  75
  76 Output:
  77
  78     <h1>A First Level Header</h1>
  79
  80     <h2>A Second Level Header</h2>
  81
  82     <p>Now is the time for all good men to come to
  83     the aid of their country. This is just a
  84     regular paragraph.</p>
  85
  86     <p>The quick brown fox jumped over the lazy
  87     dog's back.</p>
  88
  89     <h3>Header 3</h3>
  90
  91     <blockquote>
  92         <p>This is a blockquote.</p>
  93
  94         <p>This is the second paragraph in the blockquote.</p>
  95
  96         <h2>This is an H2 in a blockquote</h2>
  97     </blockquote>
  98
  99
 100
 101 ### Phrase Emphasis ###
 102
 103 Markdown uses asterisks and underscores to indicate spans of emphasis.
 104
 105 Markdown:
 106
 107     Some of these words *are emphasized*.
 108     Some of these words _are emphasized also_.
 109
 110     Use two asterisks for **strong emphasis**.
 111     Or, if you prefer, __use two underscores instead__.
 112
 113 Output:
 114
 115     <p>Some of these words <em>are emphasized</em>.
 116     Some of these words <em>are emphasized also</em>.</p>
 117
 118     <p>Use two asterisks for <strong>strong emphasis</strong>.
 119     Or, if you prefer, <strong>use two underscores instead</strong>.</p>
 120
 121
 122
 123 ## Lists ##
 124
 125 Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
 126 `+`, and `-`) as list markers. These three markers are
 127 interchangable; this:
 128
 129     *   Candy.
 130     *   Gum.
 131     *   Booze.
 132
 133 this:
 134
 135     +   Candy.
 136     +   Gum.
 137     +   Booze.
 138
 139 and this:
 140
 141     -   Candy.
 142     -   Gum.
 143     -   Booze.
 144
 145 all produce the same output:
 146
 147     <ul>
 148     <li>Candy.</li>
 149     <li>Gum.</li>
 150     <li>Booze.</li>
 151     </ul>
 152
 153 Ordered (numbered) lists use regular numbers, followed by periods, as
 154 list markers:
 155
 156     1.  Red
 157     2.  Green
 158     3.  Blue
 159
 160 Output:
 161
 162     <ol>
 163     <li>Red</li>
 164     <li>Green</li>
 165     <li>Blue</li>
 166     </ol>
 167
 168 If you put blank lines between items, you'll get `<p>` tags for the
 169 list item text. You can create multi-paragraph list items by indenting
 170 the paragraphs by 4 spaces or 1 tab:
 171
 172     *   A list item.
 173
 174         With multiple paragraphs.
 175
 176     *   Another item in the list.
 177
 178 Output:
 179
 180     <ul>
 181     <li><p>A list item.</p>
 182     <p>With multiple paragraphs.</p></li>
 183     <li><p>Another item in the list.</p></li>
 184     </ul>
 185
 186
 187
 188 ### Links ###
 189
 190 Markdown supports two styles for creating links: *inline* and
 191 *reference*. With both styles, you use square brackets to delimit the
 192 text you want to turn into a link.
 193
 194 Inline-style links use parentheses immediately after the link text.
 195 For example:
 196
 197     This is an [example link](http://example.com/).
 198
 199 Output:
 200
 201     <p>This is an <a href="http://example.com/">
 202     example link</a>.</p>
 203
 204 Optionally, you may include a title attribute in the parentheses:
 205
 206     This is an [example link](http://example.com/ "With a Title").
 207
 208 Output:
 209
 210     <p>This is an <a href="http://example.com/" title="With a Title">
 211     example link</a>.</p>
 212
 213 Reference-style links allow you to refer to your links by names, which
 214 you define elsewhere in your document:
 215
 216     I get 10 times more traffic from [Google][1] than from
 217     [Yahoo][2] or [MSN][3].
 218
 219     [1]: http://google.com/        "Google"
 220     [2]: http://search.yahoo.com/  "Yahoo Search"
 221     [3]: http://search.msn.com/    "MSN Search"
 222
 223 Output:
 224
 225     <p>I get 10 times more traffic from <a href="http://google.com/"
 226     title="Google">Google</a> than from <a href="http://search.yahoo.com/"
 227     title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
 228     title="MSN Search">MSN</a>.</p>
 229
 230 The title attribute is optional. Link names may contain letters,
 231 numbers and spaces, but are *not* case sensitive:
 232
 233     I start my morning with a cup of coffee and
 234     [The New York Times][NY Times].
 235
 236     [ny times]: http://www.nytimes.com/
 237
 238 Output:
 239
 240     <p>I start my morning with a cup of coffee and
 241     <a href="http://www.nytimes.com/">The New York Times</a>.</p>
 242
 243
 244 ### Images ###
 245
 246 Image syntax is very much like link syntax.
 247
 248 Inline (titles are optional):
 249
 250     ![alt text](/path/to/img.jpg "Title")
 251
 252 Reference-style:
 253
 254     ![alt text][id]
 255
 256     [id]: /path/to/img.jpg "Title"
 257
 258 Both of the above examples produce the same output:
 259
 260     <img src="/path/to/img.jpg" alt="alt text" title="Title" />
 261
 262
 263
 264 ### Code ###
 265
 266 In a regular paragraph, you can create code span by wrapping text in
 267 backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
 268 `>`) will automatically be translated into HTML entities. This makes
 269 it easy to use Markdown to write about HTML example code:
 270
 271     I strongly recommend against using any `<blink>` tags.
 272
 273     I wish SmartyPants used named entities like `&mdash;`
 274     instead of decimal-encoded entites like `&#8212;`.
 275
 276 Output:
 277
 278     <p>I strongly recommend against using any
 279     <code>&lt;blink&gt;</code> tags.</p>
 280
 281     <p>I wish SmartyPants used named entities like
 282     <code>&amp;mdash;</code> instead of decimal-encoded
 283     entites like <code>&amp;#8212;</code>.</p>
 284
 285
 286 To specify an entire block of pre-formatted code, indent every line of
 287 the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
 288 and `>` characters will be escaped automatically.
 289
 290 Markdown:
 291
 292     If you want your page to validate under XHTML 1.0 Strict,
 293     you've got to put paragraph tags in your blockquotes:
 294
 295         <blockquote>
 296             <p>For example.</p>
 297         </blockquote>
 298
 299 Output:
 300
 301     <p>If you want your page to validate under XHTML 1.0 Strict,
 302     you've got to put paragraph tags in your blockquotes:</p>
 303
 304     <pre><code>&lt;blockquote&gt;
 305         &lt;p&gt;For example.&lt;/p&gt;
 306     &lt;/blockquote&gt;
 307     </code></pre>