| commit | author | age | ||
| 2207d6 | 1 | Markdown: Basics |
| W | 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 |  | |
| 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 `—` | |
| 273 | instead of decimal-encoded entites like `—`. | |
| 274 | ||
| 275 | Output: | |
| 276 | ||
| 277 | <p>I strongly recommend against using any | |
| 278 | <code><blink></code> tags.</p> | |
| 279 | ||
| 280 | <p>I wish SmartyPants used named entities like | |
| 281 | <code>&mdash;</code> instead of decimal-encoded | |
| 282 | entites like <code>&#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><blockquote> | |
| 304 | <p>For example.</p> | |
| 305 | </blockquote> | |
| 306 | </code></pre> | |
