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