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. 14The <a href="/projects/markdown/syntax" title="Markdown Syntax">syntax page</a> provides complete, detailed documentation for 15every feature, but Markdown should be very easy to pick up simply by 16looking at a few examples of it in action. The examples on this page 17are written in a before/after style, showing example syntax and the 18HTML 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 21web application that allows you type your own Markdown-formatted text 22and translate it to XHTML.</p> 23 24<p><strong>Note:</strong> This document is itself written using Markdown; you 25can <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 30by one or more blank lines. (A blank line is any line that looks like a 31blank line -- a line containing nothing spaces or tabs is considered 32blank.) 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>. 35Setext-style headers for <code><h1></code> and <code><h2></code> are created by 36"underlining" with equal signs (<code>=</code>) and hyphens (<code>-</code>), respectively. 37To create an atx-style header, you put 1-6 hash marks (<code>#</code>) at the 38beginning of the line -- the number of hashes equals the resulting 39HTML header level.</p> 40 41<p>Blockquotes are indicated using email-style '<code>></code>' angle brackets.</p> 42 43<p>Markdown:</p> 44 45<pre><code>A First Level Header 46==================== 47 48A Second Level Header 49--------------------- 50 51Now is the time for all good men to come to 52the aid of their country. This is just a 53regular paragraph. 54 55The quick brown fox jumped over the lazy 56dog's back. 57 58### Header 3 59 60> This is a blockquote. 61> 62> This is the second paragraph in the blockquote. 63> 64> ## This is an H2 in a blockquote 65</code></pre> 66 67<p>Output:</p> 68 69<pre><code><h1>A First Level Header</h1> 70 71<h2>A Second Level Header</h2> 72 73<p>Now is the time for all good men to come to 74the aid of their country. This is just a 75regular paragraph.</p> 76 77<p>The quick brown fox jumped over the lazy 78dog's back.</p> 79 80<h3>Header 3</h3> 81 82<blockquote> 83 <p>This is a blockquote.</p> 84 85 <p>This is the second paragraph in the blockquote.</p> 86 87 <h2>This is an H2 in a blockquote</h2> 88</blockquote> 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*. 98Some of these words _are emphasized also_. 99 100Use two asterisks for **strong emphasis**. 101Or, if you prefer, __use two underscores instead__. 102</code></pre> 103 104<p>Output:</p> 105 106<pre><code><p>Some of these words <em>are emphasized</em>. 107Some of these words <em>are emphasized also</em>.</p> 108 109<p>Use two asterisks for <strong>strong emphasis</strong>. 110Or, if you prefer, <strong>use two underscores instead</strong>.</p> 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 117interchangable; 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><ul> 141<li>Candy.</li> 142<li>Gum.</li> 143<li>Booze.</li> 144</ul> 145</code></pre> 146 147<p>Ordered (numbered) lists use regular numbers, followed by periods, as 148list markers:</p> 149 150<pre><code>1. Red 1512. Green 1523. Blue 153</code></pre> 154 155<p>Output:</p> 156 157<pre><code><ol> 158<li>Red</li> 159<li>Green</li> 160<li>Blue</li> 161</ol> 162</code></pre> 163 164<p>If you put blank lines between items, you'll get <code><p></code> tags for the 165list item text. You can create multi-paragraph list items by indenting 166the 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><ul> 178<li><p>A list item.</p> 179<p>With multiple paragraphs.</p></li> 180<li><p>Another item in the list.</p></li> 181</ul> 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 188text you want to turn into a link.</p> 189 190<p>Inline-style links use parentheses immediately after the link text. 191For 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><p>This is an <a href="http://example.com/"> 199example link</a>.</p> 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><p>This is an <a href="http://example.com/" title="With a Title"> 210example link</a>.</p> 211</code></pre> 212 213<p>Reference-style links allow you to refer to your links by names, which 214you 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><p>I get 10 times more traffic from <a href="http://google.com/" 227title="Google">Google</a> than from <a href="http://search.yahoo.com/" 228title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/" 229title="MSN Search">MSN</a>.</p> 230</code></pre> 231 232<p>The title attribute is optional. Link names may contain letters, 233numbers 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><p>I start my morning with a cup of coffee and 244<a href="http://www.nytimes.com/">The New York Times</a>.</p> 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> 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><img src="/path/to/img.jpg" alt="alt text" title="Title" /> 266</code></pre> 267 268<h3>Code</h3> 269 270<p>In a regular paragraph, you can create code span by wrapping text in 271backtick quotes. Any ampersands (<code>&</code>) and angle brackets (<code><</code> or 272<code>></code>) will automatically be translated into HTML entities. This makes 273it easy to use Markdown to write about HTML example code:</p> 274 275<pre><code>I strongly recommend against using any `<blink>` tags. 276 277I wish SmartyPants used named entities like `&mdash;` 278instead of decimal-encoded entites like `&#8212;`. 279</code></pre> 280 281<p>Output:</p> 282 283<pre><code><p>I strongly recommend against using any 284<code>&lt;blink&gt;</code> tags.</p> 285 286<p>I wish SmartyPants used named entities like 287<code>&amp;mdash;</code> instead of decimal-encoded 288entites like <code>&amp;#8212;</code>.</p> 289</code></pre> 290 291<p>To specify an entire block of pre-formatted code, indent every line of 292the block by 4 spaces or 1 tab. Just like with code spans, <code>&</code>, <code><</code>, 293and <code>></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, 298you've got to put paragraph tags in your blockquotes: 299 300 <blockquote> 301 <p>For example.</p> 302 </blockquote> 303</code></pre> 304 305<p>Output:</p> 306 307<pre><code><p>If you want your page to validate under XHTML 1.0 Strict, 308you've got to put paragraph tags in your blockquotes:</p> 309 310<pre><code>&lt;blockquote&gt; 311 &lt;p&gt;For example.&lt;/p&gt; 312&lt;/blockquote&gt; 313</code></pre> 314</code></pre> 315
