| OLD | NEW |
|---|
| (Empty) |
| 1 <h1>Markdown: Syntax</h1> | |
| 2 | |
| 3 <ul id="ProjectSubmenu"> | |
| 4 <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li
> | |
| 5 <li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></
li> | |
| 6 <li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li
> | |
| 7 <li><a href="/projects/markdown/license" title="Pricing and License Informat
ion">License</a></li> | |
| 8 <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Din
gus</a></li> | |
| 9 </ul> | |
| 10 | |
| 11 <ul> | |
| 12 <li><a href="#overview">Overview</a> | |
| 13 <ul> | |
| 14 <li><a href="#philosophy">Philosophy</a></li> | |
| 15 <li><a href="#html">Inline HTML</a></li> | |
| 16 <li><a href="#autoescape">Automatic Escaping for Special Characters</a></li> | |
| 17 </ul></li> | |
| 18 <li><a href="#block">Block Elements</a> | |
| 19 <ul> | |
| 20 <li><a href="#p">Paragraphs and Line Breaks</a></li> | |
| 21 <li><a href="#header">Headers</a></li> | |
| 22 <li><a href="#blockquote">Blockquotes</a></li> | |
| 23 <li><a href="#list">Lists</a></li> | |
| 24 <li><a href="#precode">Code Blocks</a></li> | |
| 25 <li><a href="#hr">Horizontal Rules</a></li> | |
| 26 </ul></li> | |
| 27 <li><a href="#span">Span Elements</a> | |
| 28 <ul> | |
| 29 <li><a href="#link">Links</a></li> | |
| 30 <li><a href="#em">Emphasis</a></li> | |
| 31 <li><a href="#code">Code</a></li> | |
| 32 <li><a href="#img">Images</a></li> | |
| 33 </ul></li> | |
| 34 <li><a href="#misc">Miscellaneous</a> | |
| 35 <ul> | |
| 36 <li><a href="#backslash">Backslash Escapes</a></li> | |
| 37 <li><a href="#autolink">Automatic Links</a></li> | |
| 38 </ul></li> | |
| 39 </ul> | |
| 40 | |
| 41 <p><strong>Note:</strong> This document is itself written using Markdown; you | |
| 42 can <a href="/projects/markdown/syntax.text">see the source for it by adding '.t
ext' to the URL</a>.</p> | |
| 43 | |
| 44 <hr /> | |
| 45 | |
| 46 <h2 id="overview">Overview</h2> | |
| 47 | |
| 48 <h3 id="philosophy">Philosophy</h3> | |
| 49 | |
| 50 <p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.<
/p> | |
| 51 | |
| 52 <p>Readability, however, is emphasized above all else. A Markdown-formatted | |
| 53 document should be publishable as-is, as plain text, without looking | |
| 54 like it's been marked up with tags or formatting instructions. While | |
| 55 Markdown's syntax has been influenced by several existing text-to-HTML | |
| 56 filters -- including <a href="http://docutils.sourceforge.net/mirror/setext.html
">Setext</a>, <a href="http://www.aaronsw.com/2002/atx/">atx</a>, <a href="http:
//textism.com/tools/textile/">Textile</a>, <a href="http://docutils.sourceforge.
net/rst.html">reStructuredText</a>, | |
| 57 <a href="http://www.triptico.com/software/grutatxt.html">Grutatext</a>, and <a h
ref="http://ettext.taint.org/doc/">EtText</a> -- the single biggest source of | |
| 58 inspiration for Markdown's syntax is the format of plain text email.</p> | |
| 59 | |
| 60 <p>To this end, Markdown's syntax is comprised entirely of punctuation | |
| 61 characters, which punctuation characters have been carefully chosen so | |
| 62 as to look like what they mean. E.g., asterisks around a word actually | |
| 63 look like *emphasis*. Markdown lists look like, well, lists. Even | |
| 64 blockquotes look like quoted passages of text, assuming you've ever | |
| 65 used email.</p> | |
| 66 | |
| 67 <h3 id="html">Inline HTML</h3> | |
| 68 | |
| 69 <p>Markdown's syntax is intended for one purpose: to be used as a | |
| 70 format for <em>writing</em> for the web.</p> | |
| 71 | |
| 72 <p>Markdown is not a replacement for HTML, or even close to it. Its | |
| 73 syntax is very small, corresponding only to a very small subset of | |
| 74 HTML tags. The idea is <em>not</em> to create a syntax that makes it easier | |
| 75 to insert HTML tags. In my opinion, HTML tags are already easy to | |
| 76 insert. The idea for Markdown is to make it easy to read, write, and | |
| 77 edit prose. HTML is a <em>publishing</em> format; Markdown is a <em>writing</em> | |
| 78 format. Thus, Markdown's formatting syntax only addresses issues that | |
| 79 can be conveyed in plain text.</p> | |
| 80 | |
| 81 <p>For any markup that is not covered by Markdown's syntax, you simply | |
| 82 use HTML itself. There's no need to preface it or delimit it to | |
| 83 indicate that you're switching from Markdown to HTML; you just use | |
| 84 the tags.</p> | |
| 85 | |
| 86 <p>The only restrictions are that block-level HTML elements -- e.g. <code><di
v></code>, | |
| 87 <code><table></code>, <code><pre></code>, <code><p></code>, et
c. -- must be separated from surrounding | |
| 88 content by blank lines, and the start and end tags of the block should | |
| 89 not be indented with tabs or spaces. Markdown is smart enough not | |
| 90 to add extra (unwanted) <code><p></code> tags around HTML block-level tags
.</p> | |
| 91 | |
| 92 <p>For example, to add an HTML table to a Markdown article:</p> | |
| 93 | |
| 94 <pre><code>This is a regular paragraph. | |
| 95 | |
| 96 <table> | |
| 97 <tr> | |
| 98 <td>Foo</td> | |
| 99 </tr> | |
| 100 </table> | |
| 101 | |
| 102 This is another regular paragraph. | |
| 103 </code></pre> | |
| 104 | |
| 105 <p>Note that Markdown formatting syntax is not processed within block-level | |
| 106 HTML tags. E.g., you can't use Markdown-style <code>*emphasis*</code> inside an | |
| 107 HTML block.</p> | |
| 108 | |
| 109 <p>Span-level HTML tags -- e.g. <code><span></code>, <code><cite></c
ode>, or <code><del></code> -- can be | |
| 110 used anywhere in a Markdown paragraph, list item, or header. If you | |
| 111 want, you can even use HTML tags instead of Markdown formatting; e.g. if | |
| 112 you'd prefer to use HTML <code><a></code> or <code><img></code> tags
instead of Markdown's | |
| 113 link or image syntax, go right ahead.</p> | |
| 114 | |
| 115 <p>Unlike block-level HTML tags, Markdown syntax <em>is</em> processed within | |
| 116 span-level tags.</p> | |
| 117 | |
| 118 <h3 id="autoescape">Automatic Escaping for Special Characters</h3> | |
| 119 | |
| 120 <p>In HTML, there are two characters that demand special treatment: <code><</
code> | |
| 121 and <code>&</code>. Left angle brackets are used to start tags; ampersands a
re | |
| 122 used to denote HTML entities. If you want to use them as literal | |
| 123 characters, you must escape them as entities, e.g. <code>&lt;</code>, and | |
| 124 <code>&amp;</code>.</p> | |
| 125 | |
| 126 <p>Ampersands in particular are bedeviling for web writers. If you want to | |
| 127 write about 'AT&T', you need to write '<code>AT&amp;T</code>'. You even
need to | |
| 128 escape ampersands within URLs. Thus, if you want to link to:</p> | |
| 129 | |
| 130 <pre><code>http://images.google.com/images?num=30&q=larry+bird | |
| 131 </code></pre> | |
| 132 | |
| 133 <p>you need to encode the URL as:</p> | |
| 134 | |
| 135 <pre><code>http://images.google.com/images?num=30&amp;q=larry+bird | |
| 136 </code></pre> | |
| 137 | |
| 138 <p>in your anchor tag <code>href</code> attribute. Needless to say, this is easy
to | |
| 139 forget, and is probably the single most common source of HTML validation | |
| 140 errors in otherwise well-marked-up web sites.</p> | |
| 141 | |
| 142 <p>Markdown allows you to use these characters naturally, taking care of | |
| 143 all the necessary escaping for you. If you use an ampersand as part of | |
| 144 an HTML entity, it remains unchanged; otherwise it will be translated | |
| 145 into <code>&amp;</code>.</p> | |
| 146 | |
| 147 <p>So, if you want to include a copyright symbol in your article, you can write:
</p> | |
| 148 | |
| 149 <pre><code>&copy; | |
| 150 </code></pre> | |
| 151 | |
| 152 <p>and Markdown will leave it alone. But if you write:</p> | |
| 153 | |
| 154 <pre><code>AT&T | |
| 155 </code></pre> | |
| 156 | |
| 157 <p>Markdown will translate it to:</p> | |
| 158 | |
| 159 <pre><code>AT&amp;T | |
| 160 </code></pre> | |
| 161 | |
| 162 <p>Similarly, because Markdown supports <a href="#html">inline HTML</a>, if you
use | |
| 163 angle brackets as delimiters for HTML tags, Markdown will treat them as | |
| 164 such. But if you write:</p> | |
| 165 | |
| 166 <pre><code>4 < 5 | |
| 167 </code></pre> | |
| 168 | |
| 169 <p>Markdown will translate it to:</p> | |
| 170 | |
| 171 <pre><code>4 &lt; 5 | |
| 172 </code></pre> | |
| 173 | |
| 174 <p>However, inside Markdown code spans and blocks, angle brackets and | |
| 175 ampersands are <em>always</em> encoded automatically. This makes it easy to use | |
| 176 Markdown to write about HTML code. (As opposed to raw HTML, which is a | |
| 177 terrible format for writing about HTML syntax, because every single <code><</
code> | |
| 178 and <code>&</code> in your example code needs to be escaped.)</p> | |
| 179 | |
| 180 <hr /> | |
| 181 | |
| 182 <h2 id="block">Block Elements</h2> | |
| 183 | |
| 184 <h3 id="p">Paragraphs and Line Breaks</h3> | |
| 185 | |
| 186 <p>A paragraph is simply one or more consecutive lines of text, separated | |
| 187 by one or more blank lines. (A blank line is any line that looks like a | |
| 188 blank line -- a line containing nothing but spaces or tabs is considered | |
| 189 blank.) Normal paragraphs should not be intended with spaces or tabs.</p> | |
| 190 | |
| 191 <p>The implication of the "one or more consecutive lines of text" rule is | |
| 192 that Markdown supports "hard-wrapped" text paragraphs. This differs | |
| 193 significantly from most other text-to-HTML formatters (including Movable | |
| 194 Type's "Convert Line Breaks" option) which translate every line break | |
| 195 character in a paragraph into a <code><br /></code> tag.</p> | |
| 196 | |
| 197 <p>When you <em>do</em> want to insert a <code><br /></code> break tag usi
ng Markdown, you | |
| 198 end a line with two or more spaces, then type return.</p> | |
| 199 | |
| 200 <p>Yes, this takes a tad more effort to create a <code><br /></code>, but
a simplistic | |
| 201 "every line break is a <code><br /></code>" rule wouldn't work for Markdow
n. | |
| 202 Markdown's email-style <a href="#blockquote">blockquoting</a> and multi-paragrap
h <a href="#list">list items</a> | |
| 203 work best -- and look better -- when you format them with hard breaks.</p> | |
| 204 | |
| 205 <h3 id="header">Headers</h3> | |
| 206 | |
| 207 <p>Markdown supports two styles of headers, <a href="http://docutils.sourceforge
.net/mirror/setext.html">Setext</a> and <a href="http://www.aaronsw.com/2002/atx
/">atx</a>.</p> | |
| 208 | |
| 209 <p>Setext-style headers are "underlined" using equal signs (for first-level | |
| 210 headers) and dashes (for second-level headers). For example:</p> | |
| 211 | |
| 212 <pre><code>This is an H1 | |
| 213 ============= | |
| 214 | |
| 215 This is an H2 | |
| 216 ------------- | |
| 217 </code></pre> | |
| 218 | |
| 219 <p>Any number of underlining <code>=</code>'s or <code>-</code>'s will work.</p> | |
| 220 | |
| 221 <p>Atx-style headers use 1-6 hash characters at the start of the line, | |
| 222 corresponding to header levels 1-6. For example:</p> | |
| 223 | |
| 224 <pre><code># This is an H1 | |
| 225 | |
| 226 ## This is an H2 | |
| 227 | |
| 228 ###### This is an H6 | |
| 229 </code></pre> | |
| 230 | |
| 231 <p>Optionally, you may "close" atx-style headers. This is purely | |
| 232 cosmetic -- you can use this if you think it looks better. The | |
| 233 closing hashes don't even need to match the number of hashes | |
| 234 used to open the header. (The number of opening hashes | |
| 235 determines the header level.) :</p> | |
| 236 | |
| 237 <pre><code># This is an H1 # | |
| 238 | |
| 239 ## This is an H2 ## | |
| 240 | |
| 241 ### This is an H3 ###### | |
| 242 </code></pre> | |
| 243 | |
| 244 <h3 id="blockquote">Blockquotes</h3> | |
| 245 | |
| 246 <p>Markdown uses email-style <code>></code> characters for blockquoting. If y
ou're | |
| 247 familiar with quoting passages of text in an email message, then you | |
| 248 know how to create a blockquote in Markdown. It looks best if you hard | |
| 249 wrap the text and put a <code>></code> before every line:</p> | |
| 250 | |
| 251 <pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit
amet, | |
| 252 > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. | |
| 253 > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. | |
| 254 > | |
| 255 > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse | |
| 256 > id sem consectetuer libero luctus adipiscing. | |
| 257 </code></pre> | |
| 258 | |
| 259 <p>Markdown allows you to be lazy and only put the <code>></code> before the
first | |
| 260 line of a hard-wrapped paragraph:</p> | |
| 261 | |
| 262 <pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit
amet, | |
| 263 consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. | |
| 264 Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. | |
| 265 | |
| 266 > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse | |
| 267 id sem consectetuer libero luctus adipiscing. | |
| 268 </code></pre> | |
| 269 | |
| 270 <p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by | |
| 271 adding additional levels of <code>></code>:</p> | |
| 272 | |
| 273 <pre><code>> This is the first level of quoting. | |
| 274 > | |
| 275 > > This is nested blockquote. | |
| 276 > | |
| 277 > Back to the first level. | |
| 278 </code></pre> | |
| 279 | |
| 280 <p>Blockquotes can contain other Markdown elements, including headers, lists, | |
| 281 and code blocks:</p> | |
| 282 | |
| 283 <pre><code>> ## This is a header. | |
| 284 > | |
| 285 > 1. This is the first list item. | |
| 286 > 2. This is the second list item. | |
| 287 > | |
| 288 > Here's some example code: | |
| 289 > | |
| 290 > return shell_exec("echo $input | $markdown_script"); | |
| 291 </code></pre> | |
| 292 | |
| 293 <p>Any decent text editor should make email-style quoting easy. For | |
| 294 example, with BBEdit, you can make a selection and choose Increase | |
| 295 Quote Level from the Text menu.</p> | |
| 296 | |
| 297 <h3 id="list">Lists</h3> | |
| 298 | |
| 299 <p>Markdown supports ordered (numbered) and unordered (bulleted) lists.</p> | |
| 300 | |
| 301 <p>Unordered lists use asterisks, pluses, and hyphens -- interchangably | |
| 302 -- as list markers:</p> | |
| 303 | |
| 304 <pre><code>* Red | |
| 305 * Green | |
| 306 * Blue | |
| 307 </code></pre> | |
| 308 | |
| 309 <p>is equivalent to:</p> | |
| 310 | |
| 311 <pre><code>+ Red | |
| 312 + Green | |
| 313 + Blue | |
| 314 </code></pre> | |
| 315 | |
| 316 <p>and:</p> | |
| 317 | |
| 318 <pre><code>- Red | |
| 319 - Green | |
| 320 - Blue | |
| 321 </code></pre> | |
| 322 | |
| 323 <p>Ordered lists use numbers followed by periods:</p> | |
| 324 | |
| 325 <pre><code>1. Bird | |
| 326 2. McHale | |
| 327 3. Parish | |
| 328 </code></pre> | |
| 329 | |
| 330 <p>It's important to note that the actual numbers you use to mark the | |
| 331 list have no effect on the HTML output Markdown produces. The HTML | |
| 332 Markdown produces from the above list is:</p> | |
| 333 | |
| 334 <pre><code><ol> | |
| 335 <li>Bird</li> | |
| 336 <li>McHale</li> | |
| 337 <li>Parish</li> | |
| 338 </ol> | |
| 339 </code></pre> | |
| 340 | |
| 341 <p>If you instead wrote the list in Markdown like this:</p> | |
| 342 | |
| 343 <pre><code>1. Bird | |
| 344 1. McHale | |
| 345 1. Parish | |
| 346 </code></pre> | |
| 347 | |
| 348 <p>or even:</p> | |
| 349 | |
| 350 <pre><code>3. Bird | |
| 351 1. McHale | |
| 352 8. Parish | |
| 353 </code></pre> | |
| 354 | |
| 355 <p>you'd get the exact same HTML output. The point is, if you want to, | |
| 356 you can use ordinal numbers in your ordered Markdown lists, so that | |
| 357 the numbers in your source match the numbers in your published HTML. | |
| 358 But if you want to be lazy, you don't have to.</p> | |
| 359 | |
| 360 <p>If you do use lazy list numbering, however, you should still start the | |
| 361 list with the number 1. At some point in the future, Markdown may support | |
| 362 starting ordered lists at an arbitrary number.</p> | |
| 363 | |
| 364 <p>List markers typically start at the left margin, but may be indented by | |
| 365 up to three spaces. List markers must be followed by one or more spaces | |
| 366 or a tab.</p> | |
| 367 | |
| 368 <p>To make lists look nice, you can wrap items with hanging indents:</p> | |
| 369 | |
| 370 <pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit. | |
| 371 Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, | |
| 372 viverra nec, fringilla in, laoreet vitae, risus. | |
| 373 * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. | |
| 374 Suspendisse id sem consectetuer libero luctus adipiscing. | |
| 375 </code></pre> | |
| 376 | |
| 377 <p>But if you want to be lazy, you don't have to:</p> | |
| 378 | |
| 379 <pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit. | |
| 380 Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, | |
| 381 viverra nec, fringilla in, laoreet vitae, risus. | |
| 382 * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. | |
| 383 Suspendisse id sem consectetuer libero luctus adipiscing. | |
| 384 </code></pre> | |
| 385 | |
| 386 <p>If list items are separated by blank lines, Markdown will wrap the | |
| 387 items in <code><p></code> tags in the HTML output. For example, this input
:</p> | |
| 388 | |
| 389 <pre><code>* Bird | |
| 390 * Magic | |
| 391 </code></pre> | |
| 392 | |
| 393 <p>will turn into:</p> | |
| 394 | |
| 395 <pre><code><ul> | |
| 396 <li>Bird</li> | |
| 397 <li>Magic</li> | |
| 398 </ul> | |
| 399 </code></pre> | |
| 400 | |
| 401 <p>But this:</p> | |
| 402 | |
| 403 <pre><code>* Bird | |
| 404 | |
| 405 * Magic | |
| 406 </code></pre> | |
| 407 | |
| 408 <p>will turn into:</p> | |
| 409 | |
| 410 <pre><code><ul> | |
| 411 <li><p>Bird</p></li> | |
| 412 <li><p>Magic</p></li> | |
| 413 </ul> | |
| 414 </code></pre> | |
| 415 | |
| 416 <p>List items may consist of multiple paragraphs. Each subsequent | |
| 417 paragraph in a list item must be intended by either 4 spaces | |
| 418 or one tab:</p> | |
| 419 | |
| 420 <pre><code>1. This is a list item with two paragraphs. Lorem ipsum dolor | |
| 421 sit amet, consectetuer adipiscing elit. Aliquam hendrerit | |
| 422 mi posuere lectus. | |
| 423 | |
| 424 Vestibulum enim wisi, viverra nec, fringilla in, laoreet | |
| 425 vitae, risus. Donec sit amet nisl. Aliquam semper ipsum | |
| 426 sit amet velit. | |
| 427 | |
| 428 2. Suspendisse id sem consectetuer libero luctus adipiscing. | |
| 429 </code></pre> | |
| 430 | |
| 431 <p>It looks nice if you indent every line of the subsequent | |
| 432 paragraphs, but here again, Markdown will allow you to be | |
| 433 lazy:</p> | |
| 434 | |
| 435 <pre><code>* This is a list item with two paragraphs. | |
| 436 | |
| 437 This is the second paragraph in the list item. You're | |
| 438 only required to indent the first line. Lorem ipsum dolor | |
| 439 sit amet, consectetuer adipiscing elit. | |
| 440 | |
| 441 * Another item in the same list. | |
| 442 </code></pre> | |
| 443 | |
| 444 <p>To put a blockquote within a list item, the blockquote's <code>></code> | |
| 445 delimiters need to be indented:</p> | |
| 446 | |
| 447 <pre><code>* A list item with a blockquote: | |
| 448 | |
| 449 > This is a blockquote | |
| 450 > inside a list item. | |
| 451 </code></pre> | |
| 452 | |
| 453 <p>To put a code block within a list item, the code block needs | |
| 454 to be indented <em>twice</em> -- 8 spaces or two tabs:</p> | |
| 455 | |
| 456 <pre><code>* A list item with a code block: | |
| 457 | |
| 458 <code goes here> | |
| 459 </code></pre> | |
| 460 | |
| 461 <p>It's worth noting that it's possible to trigger an ordered list by | |
| 462 accident, by writing something like this:</p> | |
| 463 | |
| 464 <pre><code>1986. What a great season. | |
| 465 </code></pre> | |
| 466 | |
| 467 <p>In other words, a <em>number-period-space</em> sequence at the beginning of a | |
| 468 line. To avoid this, you can backslash-escape the period:</p> | |
| 469 | |
| 470 <pre><code>1986\. What a great season. | |
| 471 </code></pre> | |
| 472 | |
| 473 <h3 id="precode">Code Blocks</h3> | |
| 474 | |
| 475 <p>Pre-formatted code blocks are used for writing about programming or | |
| 476 markup source code. Rather than forming normal paragraphs, the lines | |
| 477 of a code block are interpreted literally. Markdown wraps a code block | |
| 478 in both <code><pre></code> and <code><code></code> tags.</p> | |
| 479 | |
| 480 <p>To produce a code block in Markdown, simply indent every line of the | |
| 481 block by at least 4 spaces or 1 tab. For example, given this input:</p> | |
| 482 | |
| 483 <pre><code>This is a normal paragraph: | |
| 484 | |
| 485 This is a code block. | |
| 486 </code></pre> | |
| 487 | |
| 488 <p>Markdown will generate:</p> | |
| 489 | |
| 490 <pre><code><p>This is a normal paragraph:</p> | |
| 491 | |
| 492 <pre><code>This is a code block. | |
| 493 </code></pre> | |
| 494 </code></pre> | |
| 495 | |
| 496 <p>One level of indentation -- 4 spaces or 1 tab -- is removed from each | |
| 497 line of the code block. For example, this:</p> | |
| 498 | |
| 499 <pre><code>Here is an example of AppleScript: | |
| 500 | |
| 501 tell application "Foo" | |
| 502 beep | |
| 503 end tell | |
| 504 </code></pre> | |
| 505 | |
| 506 <p>will turn into:</p> | |
| 507 | |
| 508 <pre><code><p>Here is an example of AppleScript:</p> | |
| 509 | |
| 510 <pre><code>tell application "Foo" | |
| 511 beep | |
| 512 end tell | |
| 513 </code></pre> | |
| 514 </code></pre> | |
| 515 | |
| 516 <p>A code block continues until it reaches a line that is not indented | |
| 517 (or the end of the article).</p> | |
| 518 | |
| 519 <p>Within a code block, ampersands (<code>&</code>) and angle brackets (<cod
e><</code> and <code>></code>) | |
| 520 are automatically converted into HTML entities. This makes it very | |
| 521 easy to include example HTML source code using Markdown -- just paste | |
| 522 it and indent it, and Markdown will handle the hassle of encoding the | |
| 523 ampersands and angle brackets. For example, this:</p> | |
| 524 | |
| 525 <pre><code> <div class="footer"> | |
| 526 &copy; 2004 Foo Corporation | |
| 527 </div> | |
| 528 </code></pre> | |
| 529 | |
| 530 <p>will turn into:</p> | |
| 531 | |
| 532 <pre><code><pre><code>&lt;div class="footer"&gt; | |
| 533 &amp;copy; 2004 Foo Corporation | |
| 534 &lt;/div&gt; | |
| 535 </code></pre> | |
| 536 </code></pre> | |
| 537 | |
| 538 <p>Regular Markdown syntax is not processed within code blocks. E.g., | |
| 539 asterisks are just literal asterisks within a code block. This means | |
| 540 it's also easy to use Markdown to write about Markdown's own syntax.</p> | |
| 541 | |
| 542 <h3 id="hr">Horizontal Rules</h3> | |
| 543 | |
| 544 <p>You can produce a horizontal rule tag (<code><hr /></code>) by placing
three or | |
| 545 more hyphens, asterisks, or underscores on a line by themselves. If you | |
| 546 wish, you may use spaces between the hyphens or asterisks. Each of the | |
| 547 following lines will produce a horizontal rule:</p> | |
| 548 | |
| 549 <pre><code>* * * | |
| 550 | |
| 551 *** | |
| 552 | |
| 553 ***** | |
| 554 | |
| 555 - - - | |
| 556 | |
| 557 --------------------------------------- | |
| 558 | |
| 559 _ _ _ | |
| 560 </code></pre> | |
| 561 | |
| 562 <hr /> | |
| 563 | |
| 564 <h2 id="span">Span Elements</h2> | |
| 565 | |
| 566 <h3 id="link">Links</h3> | |
| 567 | |
| 568 <p>Markdown supports two style of links: <em>inline</em> and <em>reference</em>.
</p> | |
| 569 | |
| 570 <p>In both styles, the link text is delimited by [square brackets].</p> | |
| 571 | |
| 572 <p>To create an inline link, use a set of regular parentheses immediately | |
| 573 after the link text's closing square bracket. Inside the parentheses, | |
| 574 put the URL where you want the link to point, along with an <em>optional</em> | |
| 575 title for the link, surrounded in quotes. For example:</p> | |
| 576 | |
| 577 <pre><code>This is [an example](http://example.com/ "Title") inline link. | |
| 578 | |
| 579 [This link](http://example.net/) has no title attribute. | |
| 580 </code></pre> | |
| 581 | |
| 582 <p>Will produce:</p> | |
| 583 | |
| 584 <pre><code><p>This is <a href="http://example.com/" title="Title"> | |
| 585 an example</a> inline link.</p> | |
| 586 | |
| 587 <p><a href="http://example.net/">This link</a> has no | |
| 588 title attribute.</p> | |
| 589 </code></pre> | |
| 590 | |
| 591 <p>If you're referring to a local resource on the same server, you can | |
| 592 use relative paths:</p> | |
| 593 | |
| 594 <pre><code>See my [About](/about/) page for details. | |
| 595 </code></pre> | |
| 596 | |
| 597 <p>Reference-style links use a second set of square brackets, inside | |
| 598 which you place a label of your choosing to identify the link:</p> | |
| 599 | |
| 600 <pre><code>This is [an example][id] reference-style link. | |
| 601 </code></pre> | |
| 602 | |
| 603 <p>You can optionally use a space to separate the sets of brackets:</p> | |
| 604 | |
| 605 <pre><code>This is [an example] [id] reference-style link. | |
| 606 </code></pre> | |
| 607 | |
| 608 <p>Then, anywhere in the document, you define your link label like this, | |
| 609 on a line by itself:</p> | |
| 610 | |
| 611 <pre><code>[id]: http://example.com/ "Optional Title Here" | |
| 612 </code></pre> | |
| 613 | |
| 614 <p>That is:</p> | |
| 615 | |
| 616 <ul> | |
| 617 <li>Square brackets containing the link identifier (optionally | |
| 618 indented from the left margin using up to three spaces);</li> | |
| 619 <li>followed by a colon;</li> | |
| 620 <li>followed by one or more spaces (or tabs);</li> | |
| 621 <li>followed by the URL for the link;</li> | |
| 622 <li>optionally followed by a title attribute for the link, enclosed | |
| 623 in double or single quotes.</li> | |
| 624 </ul> | |
| 625 | |
| 626 <p>The link URL may, optionally, be surrounded by angle brackets:</p> | |
| 627 | |
| 628 <pre><code>[id]: <http://example.com/> "Optional Title Here" | |
| 629 </code></pre> | |
| 630 | |
| 631 <p>You can put the title attribute on the next line and use extra spaces | |
| 632 or tabs for padding, which tends to look better with longer URLs:</p> | |
| 633 | |
| 634 <pre><code>[id]: http://example.com/longish/path/to/resource/here | |
| 635 "Optional Title Here" | |
| 636 </code></pre> | |
| 637 | |
| 638 <p>Link definitions are only used for creating links during Markdown | |
| 639 processing, and are stripped from your document in the HTML output.</p> | |
| 640 | |
| 641 <p>Link definition names may constist of letters, numbers, spaces, and punctuati
on -- but they are <em>not</em> case sensitive. E.g. these two links:</p> | |
| 642 | |
| 643 <pre><code>[link text][a] | |
| 644 [link text][A] | |
| 645 </code></pre> | |
| 646 | |
| 647 <p>are equivalent.</p> | |
| 648 | |
| 649 <p>The <em>implicit link name</em> shortcut allows you to omit the name of the | |
| 650 link, in which case the link text itself is used as the name. | |
| 651 Just use an empty set of square brackets -- e.g., to link the word | |
| 652 "Google" to the google.com web site, you could simply write:</p> | |
| 653 | |
| 654 <pre><code>[Google][] | |
| 655 </code></pre> | |
| 656 | |
| 657 <p>And then define the link:</p> | |
| 658 | |
| 659 <pre><code>[Google]: http://google.com/ | |
| 660 </code></pre> | |
| 661 | |
| 662 <p>Because link names may contain spaces, this shortcut even works for | |
| 663 multiple words in the link text:</p> | |
| 664 | |
| 665 <pre><code>Visit [Daring Fireball][] for more information. | |
| 666 </code></pre> | |
| 667 | |
| 668 <p>And then define the link:</p> | |
| 669 | |
| 670 <pre><code>[Daring Fireball]: http://daringfireball.net/ | |
| 671 </code></pre> | |
| 672 | |
| 673 <p>Link definitions can be placed anywhere in your Markdown document. I | |
| 674 tend to put them immediately after each paragraph in which they're | |
| 675 used, but if you want, you can put them all at the end of your | |
| 676 document, sort of like footnotes.</p> | |
| 677 | |
| 678 <p>Here's an example of reference links in action:</p> | |
| 679 | |
| 680 <pre><code>I get 10 times more traffic from [Google] [1] than from | |
| 681 [Yahoo] [2] or [MSN] [3]. | |
| 682 | |
| 683 [1]: http://google.com/ "Google" | |
| 684 [2]: http://search.yahoo.com/ "Yahoo Search" | |
| 685 [3]: http://search.msn.com/ "MSN Search" | |
| 686 </code></pre> | |
| 687 | |
| 688 <p>Using the implicit link name shortcut, you could instead write:</p> | |
| 689 | |
| 690 <pre><code>I get 10 times more traffic from [Google][] than from | |
| 691 [Yahoo][] or [MSN][]. | |
| 692 | |
| 693 [google]: http://google.com/ "Google" | |
| 694 [yahoo]: http://search.yahoo.com/ "Yahoo Search" | |
| 695 [msn]: http://search.msn.com/ "MSN Search" | |
| 696 </code></pre> | |
| 697 | |
| 698 <p>Both of the above examples will produce the following HTML output:</p> | |
| 699 | |
| 700 <pre><code><p>I get 10 times more traffic from <a href="http://google.c
om/" | |
| 701 title="Google">Google</a> than from | |
| 702 <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a> | |
| 703 or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</
p> | |
| 704 </code></pre> | |
| 705 | |
| 706 <p>For comparison, here is the same paragraph written using | |
| 707 Markdown's inline link style:</p> | |
| 708 | |
| 709 <pre><code>I get 10 times more traffic from [Google](http://google.com/ "Google"
) | |
| 710 than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or | |
| 711 [MSN](http://search.msn.com/ "MSN Search"). | |
| 712 </code></pre> | |
| 713 | |
| 714 <p>The point of reference-style links is not that they're easier to | |
| 715 write. The point is that with reference-style links, your document | |
| 716 source is vastly more readable. Compare the above examples: using | |
| 717 reference-style links, the paragraph itself is only 81 characters | |
| 718 long; with inline-style links, it's 176 characters; and as raw HTML, | |
| 719 it's 234 characters. In the raw HTML, there's more markup than there | |
| 720 is text.</p> | |
| 721 | |
| 722 <p>With Markdown's reference-style links, a source document much more | |
| 723 closely resembles the final output, as rendered in a browser. By | |
| 724 allowing you to move the markup-related metadata out of the paragraph, | |
| 725 you can add links without interrupting the narrative flow of your | |
| 726 prose.</p> | |
| 727 | |
| 728 <h3 id="em">Emphasis</h3> | |
| 729 | |
| 730 <p>Markdown treats asterisks (<code>*</code>) and underscores (<code>_</code>) a
s indicators of | |
| 731 emphasis. Text wrapped with one <code>*</code> or <code>_</code> will be wrapped
with an | |
| 732 HTML <code><em></code> tag; double <code>*</code>'s or <code>_</code>'s wi
ll be wrapped with an HTML | |
| 733 <code><strong></code> tag. E.g., this input:</p> | |
| 734 | |
| 735 <pre><code>*single asterisks* | |
| 736 | |
| 737 _single underscores_ | |
| 738 | |
| 739 **double asterisks** | |
| 740 | |
| 741 __double underscores__ | |
| 742 </code></pre> | |
| 743 | |
| 744 <p>will produce:</p> | |
| 745 | |
| 746 <pre><code><em>single asterisks</em> | |
| 747 | |
| 748 <em>single underscores</em> | |
| 749 | |
| 750 <strong>double asterisks</strong> | |
| 751 | |
| 752 <strong>double underscores</strong> | |
| 753 </code></pre> | |
| 754 | |
| 755 <p>You can use whichever style you prefer; the lone restriction is that | |
| 756 the same character must be used to open and close an emphasis span.</p> | |
| 757 | |
| 758 <p>Emphasis can be used in the middle of a word:</p> | |
| 759 | |
| 760 <pre><code>un*fucking*believable | |
| 761 </code></pre> | |
| 762 | |
| 763 <p>But if you surround an <code>*</code> or <code>_</code> with spaces, it'll be
treated as a | |
| 764 literal asterisk or underscore.</p> | |
| 765 | |
| 766 <p>To produce a literal asterisk or underscore at a position where it | |
| 767 would otherwise be used as an emphasis delimiter, you can backslash | |
| 768 escape it:</p> | |
| 769 | |
| 770 <pre><code>\*this text is surrounded by literal asterisks\* | |
| 771 </code></pre> | |
| 772 | |
| 773 <h3 id="code">Code</h3> | |
| 774 | |
| 775 <p>To indicate a span of code, wrap it with backtick quotes (<code>`</code>). | |
| 776 Unlike a pre-formatted code block, a code span indicates code within a | |
| 777 normal paragraph. For example:</p> | |
| 778 | |
| 779 <pre><code>Use the `printf()` function. | |
| 780 </code></pre> | |
| 781 | |
| 782 <p>will produce:</p> | |
| 783 | |
| 784 <pre><code><p>Use the <code>printf()</code> function.</p>
; | |
| 785 </code></pre> | |
| 786 | |
| 787 <p>To include a literal backtick character within a code span, you can use | |
| 788 multiple backticks as the opening and closing delimiters:</p> | |
| 789 | |
| 790 <pre><code>``There is a literal backtick (`) here.`` | |
| 791 </code></pre> | |
| 792 | |
| 793 <p>which will produce this:</p> | |
| 794 | |
| 795 <pre><code><p><code>There is a literal backtick (`) here.</code&g
t;</p> | |
| 796 </code></pre> | |
| 797 | |
| 798 <p>The backtick delimiters surrounding a code span may include spaces -- | |
| 799 one after the opening, one before the closing. This allows you to place | |
| 800 literal backtick characters at the beginning or end of a code span:</p> | |
| 801 | |
| 802 <pre><code>A single backtick in a code span: `` ` `` | |
| 803 | |
| 804 A backtick-delimited string in a code span: `` `foo` `` | |
| 805 </code></pre> | |
| 806 | |
| 807 <p>will produce:</p> | |
| 808 | |
| 809 <pre><code><p>A single backtick in a code span: <code>`</code>
</p> | |
| 810 | |
| 811 <p>A backtick-delimited string in a code span: <code>`foo`</code&
gt;</p> | |
| 812 </code></pre> | |
| 813 | |
| 814 <p>With a code span, ampersands and angle brackets are encoded as HTML | |
| 815 entities automatically, which makes it easy to include example HTML | |
| 816 tags. Markdown will turn this:</p> | |
| 817 | |
| 818 <pre><code>Please don't use any `<blink>` tags. | |
| 819 </code></pre> | |
| 820 | |
| 821 <p>into:</p> | |
| 822 | |
| 823 <pre><code><p>Please don't use any <code>&lt;blink&gt;</c
ode> tags.</p> | |
| 824 </code></pre> | |
| 825 | |
| 826 <p>You can write this:</p> | |
| 827 | |
| 828 <pre><code>`&#8212;` is the decimal-encoded equivalent of `&mdash;`. | |
| 829 </code></pre> | |
| 830 | |
| 831 <p>to produce:</p> | |
| 832 | |
| 833 <pre><code><p><code>&amp;#8212;</code> is the decimal-enco
ded | |
| 834 equivalent of <code>&amp;mdash;</code>.</p> | |
| 835 </code></pre> | |
| 836 | |
| 837 <h3 id="img">Images</h3> | |
| 838 | |
| 839 <p>Admittedly, it's fairly difficult to devise a "natural" syntax for | |
| 840 placing images into a plain text document format.</p> | |
| 841 | |
| 842 <p>Markdown uses an image syntax that is intended to resemble the syntax | |
| 843 for links, allowing for two styles: <em>inline</em> and <em>reference</em>.</p> | |
| 844 | |
| 845 <p>Inline image syntax looks like this:</p> | |
| 846 | |
| 847 <pre><code> | |
| 848 | |
| 849  | |
| 850 </code></pre> | |
| 851 | |
| 852 <p>That is:</p> | |
| 853 | |
| 854 <ul> | |
| 855 <li>An exclamation mark: <code>!</code>;</li> | |
| 856 <li>followed by a set of square brackets, containing the <code>alt</code> | |
| 857 attribute text for the image;</li> | |
| 858 <li>followed by a set of parentheses, containing the URL or path to | |
| 859 the image, and an optional <code>title</code> attribute enclosed in double | |
| 860 or single quotes.</li> | |
| 861 </ul> | |
| 862 | |
| 863 <p>Reference-style image syntax looks like this:</p> | |
| 864 | |
| 865 <pre><code>![Alt text][id] | |
| 866 </code></pre> | |
| 867 | |
| 868 <p>Where "id" is the name of a defined image reference. Image references | |
| 869 are defined using syntax identical to link references:</p> | |
| 870 | |
| 871 <pre><code>[id]: url/to/image "Optional title attribute" | |
| 872 </code></pre> | |
| 873 | |
| 874 <p>As of this writing, Markdown has no syntax for specifying the | |
| 875 dimensions of an image; if this is important to you, you can simply | |
| 876 use regular HTML <code><img></code> tags.</p> | |
| 877 | |
| 878 <hr /> | |
| 879 | |
| 880 <h2 id="misc">Miscellaneous</h2> | |
| 881 | |
| 882 <h3 id="autolink">Automatic Links</h3> | |
| 883 | |
| 884 <p>Markdown supports a shortcut style for creating "automatic" links for URLs an
d email addresses: simply surround the URL or email address with angle brackets.
What this means is that if you want to show the actual text of a URL or email a
ddress, and also have it be a clickable link, you can do this:</p> | |
| 885 | |
| 886 <pre><code><http://example.com/> | |
| 887 </code></pre> | |
| 888 | |
| 889 <p>Markdown will turn this into:</p> | |
| 890 | |
| 891 <pre><code><a href="http://example.com/">http://example.com/</a> | |
| 892 </code></pre> | |
| 893 | |
| 894 <p>Automatic links for email addresses work similarly, except that | |
| 895 Markdown will also perform a bit of randomized decimal and hex | |
| 896 entity-encoding to help obscure your address from address-harvesting | |
| 897 spambots. For example, Markdown will turn this:</p> | |
| 898 | |
| 899 <pre><code><address@example.com> | |
| 900 </code></pre> | |
| 901 | |
| 902 <p>into something like this:</p> | |
| 903 | |
| 904 <pre><code><a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&
#x61;&#x64;&#x64;&#x72;&#x65; | |
| 905 &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&
amp;#x6C;e&#x2E;&#99;&#111; | |
| 906 &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&
#115;&#64;&#101;&#120;&#x61; | |
| 907 &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a> | |
| 908 </code></pre> | |
| 909 | |
| 910 <p>which will render in a browser as a clickable link to "address@example.com".<
/p> | |
| 911 | |
| 912 <p>(This sort of entity-encoding trick will indeed fool many, if not | |
| 913 most, address-harvesting bots, but it definitely won't fool all of | |
| 914 them. It's better than nothing, but an address published in this way | |
| 915 will probably eventually start receiving spam.)</p> | |
| 916 | |
| 917 <h3 id="backslash">Backslash Escapes</h3> | |
| 918 | |
| 919 <p>Markdown allows you to use backslash escapes to generate literal | |
| 920 characters which would otherwise have special meaning in Markdown's | |
| 921 formatting syntax. For example, if you wanted to surround a word with | |
| 922 literal asterisks (instead of an HTML <code><em></code> tag), you can back
slashes | |
| 923 before the asterisks, like this:</p> | |
| 924 | |
| 925 <pre><code>\*literal asterisks\* | |
| 926 </code></pre> | |
| 927 | |
| 928 <p>Markdown provides backslash escapes for the following characters:</p> | |
| 929 | |
| 930 <pre><code>\ backslash | |
| 931 ` backtick | |
| 932 * asterisk | |
| 933 _ underscore | |
| 934 {} curly braces | |
| 935 [] square brackets | |
| 936 () parentheses | |
| 937 # hash mark | |
| 938 + plus sign | |
| 939 - minus sign (hyphen) | |
| 940 . dot | |
| 941 ! exclamation mark | |
| 942 </code></pre> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 786953007:
npm_modules: Fork bower_components into Polymer 0.4.0 and 0.5.0 versions (Closed)
Base URL: https://chromium.googlesource.com/infra/third_party/npm_modules.git@master