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