Home | History | Annotate | Download | only in Tests_2004
      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>
    307