testdata/Markdown Documentation - Basics.text (view raw)
1Markdown: Basics
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
13Getting the Gist of Markdown's Formatting Syntax
14------------------------------------------------
15
16This page offers a brief overview of what it's like to use Markdown.
17The [syntax page] [s] provides complete, detailed documentation for
18every feature, but Markdown should be very easy to pick up simply by
19looking at a few examples of it in action. The examples on this page
20are written in a before/after style, showing example syntax and the
21HTML output produced by Markdown.
22
23It's also helpful to simply try Markdown out; the [Dingus] [d] is a
24web application that allows you type your own Markdown-formatted text
25and translate it to XHTML.
26
27**Note:** This document is itself written using Markdown; you
28can [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
37A paragraph is simply one or more consecutive lines of text, separated
38by one or more blank lines. (A blank line is any line that looks like a
39blank line -- a line containing nothing spaces or tabs is considered
40blank.) Normal paragraphs should not be intended with spaces or tabs.
41
42Markdown offers two styles of headers: *Setext* and *atx*.
43Setext-style headers for `<h1>` and `<h2>` are created by
44"underlining" with equal signs (`=`) and hyphens (`-`), respectively.
45To create an atx-style header, you put 1-6 hash marks (`#`) at the
46beginning of the line -- the number of hashes equals the resulting
47HTML header level.
48
49Blockquotes are indicated using email-style '`>`' angle brackets.
50
51Markdown:
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
75Output:
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
102Markdown uses asterisks and underscores to indicate spans of emphasis.
103
104Markdown:
105
106Markdown: Basics
107================
108
109<ul id="ProjectSubmenu">
110 <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
111 <li><a class="selected" title="Markdown Basics">Basics</a></li>
112 <li><a href="/projects/markdown/syntax" title="Markdown Syntax Documentation">Syntax</a></li>
113 <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
114 <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
115</ul>
116
117
118Getting the Gist of Markdown's Formatting Syntax
119------------------------------------------------
120
121This page offers a brief overview of what it's like to use Markdown.
122The [syntax page] [s] provides complete, detailed documentation for
123every feature, but Markdown should be very easy to pick up simply by
124looking at a few examples of it in action. The examples on this page
125are written in a before/after style, showing example syntax and the
126HTML output produced by Markdown.
127
128It's also helpful to simply try Markdown out; the [Dingus] [d] is a
129web application that allows you type your own Markdown-formatted text
130and translate it to XHTML.
131
132**Note:** This document is itself written using Markdown; you
133can [see the source for it by adding '.text' to the URL] [src].
134
135 [s]: /projects/markdown/syntax "Markdown Syntax"
136 [d]: /projects/markdown/dingus "Markdown Dingus"
137 [src]: /projects/markdown/basics.text
138
139
140## Paragraphs, Headers, Blockquotes ##
141
142A paragraph is simply one or more consecutive lines of text, separated
143by one or more blank lines. (A blank line is any line that looks like a
144blank line -- a line containing nothing spaces or tabs is considered
145blank.) Normal paragraphs should not be intended with spaces or tabs.
146
147Markdown offers two styles of headers: *Setext* and *atx*.
148Setext-style headers for `<h1>` and `<h2>` are created by
149"underlining" with equal signs (`=`) and hyphens (`-`), respectively.
150To create an atx-style header, you put 1-6 hash marks (`#`) at the
151beginning of the line -- the number of hashes equals the resulting
152HTML header level.
153
154Blockquotes are indicated using email-style '`>`' angle brackets.
155
156Markdown:
157
158 A First Level Header
159 ====================
160
161 A Second Level Header
162 ---------------------
163
164 Now is the time for all good men to come to
165 the aid of their country. This is just a
166 regular paragraph.
167
168 The quick brown fox jumped over the lazy
169 dog's back.
170
171 ### Header 3
172
173 > This is a blockquote.
174 >
175 > This is the second paragraph in the blockquote.
176 >
177 > ## This is an H2 in a blockquote
178
179
180Output:
181
182 <h1>A First Level Header</h1>
183
184 <h2>A Second Level Header</h2>
185
186 <p>Now is the time for all good men to come to
187 the aid of their country. This is just a
188 regular paragraph.</p>
189
190 <p>The quick brown fox jumped over the lazy
191 dog's back.</p>
192
193 <h3>Header 3</h3>
194
195 <blockquote>
196 <p>This is a blockquote.</p>
197
198 <p>This is the second paragraph in the blockquote.</p>
199
200 <h2>This is an H2 in a blockquote</h2>
201 </blockquote>
202
203
204
205### Phrase Emphasis ###
206
207Markdown uses asterisks and underscores to indicate spans of emphasis.
208
209Markdown:
210
211 Some of these words *are emphasized*.
212 Some of these words _are emphasized also_.
213
214 Use two asterisks for **strong emphasis**.
215 Or, if you prefer, __use two underscores instead__.
216
217Output:
218
219 <p>Some of these words <em>are emphasized</em>.
220 Some of these words <em>are emphasized also</em>.</p>
221
222 <p>Use two asterisks for <strong>strong emphasis</strong>.
223 Or, if you prefer, <strong>use two underscores instead</strong>.</p>
224
225
226
227## Lists ##
228
229Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
230`+`, and `-`) as list markers. These three markers are
231interchangable; this:
232
233 * Candy.
234 * Gum.
235 * Booze.
236
237this:
238
239 + Candy.
240 + Gum.
241 + Booze.
242
243and this:
244
245 - Candy.
246 - Gum.
247 - Booze.
248
249all produce the same output:
250
251 <ul>
252 <li>Candy.</li>
253 <li>Gum.</li>
254 <li>Booze.</li>
255 </ul>
256
257Ordered (numbered) lists use regular numbers, followed by periods, as
258list markers:
259
260 1. Red
261 2. Green
262 3. Blue
263
264Output:
265
266 <ol>
267 <li>Red</li>
268 <li>Green</li>
269 <li>Blue</li>
270 </ol>
271
272If you put blank lines between items, you'll get `<p>` tags for the
273list item text. You can create multi-paragraph list items by indenting
274the paragraphs by 4 spaces or 1 tab:
275
276 * A list item.
277
278 With multiple paragraphs.
279
280 * Another item in the list.
281
282Output:
283
284 <ul>
285 <li><p>A list item.</p>
286 <p>With multiple paragraphs.</p></li>
287 <li><p>Another item in the list.</p></li>
288 </ul>
289
290
291
292### Links ###
293
294Markdown supports two styles for creating links: *inline* and
295*reference*. With both styles, you use square brackets to delimit the
296text you want to turn into a link.
297
298Inline-style links use parentheses immediately after the link text.
299For example:
300
301 This is an [example link](http://example.com/).
302
303Output:
304
305 <p>This is an <a href="http://example.com/">
306 example link</a>.</p>
307
308Optionally, you may include a title attribute in the parentheses:
309
310 This is an [example link](http://example.com/ "With a Title").
311
312Output:
313
314 <p>This is an <a href="http://example.com/" title="With a Title">
315 example link</a>.</p>
316
317Reference-style links allow you to refer to your links by names, which
318you define elsewhere in your document:
319
320 I get 10 times more traffic from [Google][1] than from
321 [Yahoo][2] or [MSN][3].
322
323 [1]: http://google.com/ "Google"
324 [2]: http://search.yahoo.com/ "Yahoo Search"
325 [3]: http://search.msn.com/ "MSN Search"
326
327Output:
328
329 <p>I get 10 times more traffic from <a href="http://google.com/"
330 title="Google">Google</a> than from <a href="http://search.yahoo.com/"
331 title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
332 title="MSN Search">MSN</a>.</p>
333
334The title attribute is optional. Link names may contain letters,
335numbers and spaces, but are *not* case sensitive:
336
337 I start my morning with a cup of coffee and
338 [The New York Times][NY Times].
339
340 [ny times]: http://www.nytimes.com/
341
342Output:
343
344 <p>I start my morning with a cup of coffee and
345 <a href="http://www.nytimes.com/">The New York Times</a>.</p>
346
347It is also common to find other protocols such as ftp used for links:
348
349Input:
350
351 For example one may test download speeds [here](ftp://speedtest.tele2.net/)
352
353Output:
354
355 <p>For example one may test download speeds <a href="ftp://speedtest.tele2.net/">here</a>.</p>
356
357### Images ###
358
359Image syntax is very much like link syntax.
360
361Inline (titles are optional):
362
363 
364
365Reference-style:
366
367 ![alt text][id]
368
369 [id]: /path/to/img.jpg "Title"
370
371Both of the above examples produce the same output:
372
373 <img src="/path/to/img.jpg" alt="alt text" title="Title" />
374
375
376
377### Code ###
378
379In a regular paragraph, you can create code span by wrapping text in
380backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
381`>`) will automatically be translated into HTML entities. This makes
382it easy to use Markdown to write about HTML example code:
383
384 I strongly recommend against using any `<blink>` tags.
385
386 I wish SmartyPants used named entities like `—`
387 instead of decimal-encoded entites like `—`.
388
389Output:
390
391 <p>I strongly recommend against using any
392 <code><blink></code> tags.</p>
393
394 <p>I wish SmartyPants used named entities like
395 <code>&mdash;</code> instead of decimal-encoded
396 entites like <code>&#8212;</code>.</p>
397
398
399To specify an entire block of pre-formatted code, indent every line of
400the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
401and `>` characters will be escaped automatically.
402
403Markdown:
404
405 If you want your page to validate under XHTML 1.0 Strict,
406 you've got to put paragraph tags in your blockquotes:
407
408 <blockquote>
409 <p>For example.</p>
410 </blockquote>
411
412Output:
413
414 <p>If you want your page to validate under XHTML 1.0 Strict,
415 you've got to put paragraph tags in your blockquotes:</p>
416
417 <pre><code><blockquote>
418 <p>For example.</p>
419 </blockquote>
420 </code></pre>