Markdown mode

x
 
1
Markdown: 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
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
39
a blank line -- a line containing nothing but spaces or tabs is
40
considered blank.) Normal paragraphs should not be indented with
41
spaces or tabs.
42
43
Markdown offers two styles of headers: *Setext* and *atx*.
44
Setext-style headers for `<h1>` and `<h2>` are created by
45
"underlining" with equal signs (`=`) and hyphens (`-`), respectively.
46
To create an atx-style header, you put 1-6 hash marks (`#`) at the
47
beginning of the line -- the number of hashes equals the resulting
48
HTML header level.
49
50
Blockquotes are indicated using email-style '`>`' angle brackets.
51
52
Markdown:
53
54
    A First Level Header
55
    ====================
56
    
57
    A Second Level Header
58
    ---------------------
59
60
    Now is the time for all good men to come to
61
    the aid of their country. This is just a
62
    regular paragraph.
63
64
    The quick brown fox jumped over the lazy
65
    dog's back.
66
    
67
    ### Header 3
68
69
    > This is a blockquote.
70
    > 
71
    > This is the second paragraph in the blockquote.
72
    >
73
    > ## This is an H2 in a blockquote
74
75
76
Output:
77
78
    <h1>A First Level Header</h1>
79
    
80
    <h2>A Second Level Header</h2>
81
    
82
    <p>Now is the time for all good men to come to
83
    the aid of their country. This is just a
84
    regular paragraph.</p>
85
    
86
    <p>The quick brown fox jumped over the lazy
87
    dog's back.</p>
88
    
89
    <h3>Header 3</h3>
90
    
91
    <blockquote>
92
        <p>This is a blockquote.</p>
93
        
94
        <p>This is the second paragraph in the blockquote.</p>
95
        
96
        <h2>This is an H2 in a blockquote</h2>
97
    </blockquote>
98
99
100
101
### Phrase Emphasis ###
102
103
Markdown uses asterisks and underscores to indicate spans of emphasis.
104
105
Markdown:
106
107
    Some of these words *are emphasized*.
108
    Some of these words _are emphasized also_.
109
    
110
    Use two asterisks for **strong emphasis**.
111
    Or, if you prefer, __use two underscores instead__.
112
113
Output:
114
115
    <p>Some of these words <em>are emphasized</em>.
116
    Some of these words <em>are emphasized also</em>.</p>
117
    
118
    <p>Use two asterisks for <strong>strong emphasis</strong>.
119
    Or, if you prefer, <strong>use two underscores instead</strong>.</p>
120
   
121
122
123
## Lists ##
124
125
Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
126
`+`, and `-`) as list markers. These three markers are
127
interchangable; this:
128
129
    *   Candy.
130
    *   Gum.
131
    *   Booze.
132
133
this:
134
135
    +   Candy.
136
    +   Gum.
137
    +   Booze.
138
139
and this:
140
141
    -   Candy.
142
    -   Gum.
143
    -   Booze.
144
145
all produce the same output:
146
147
    <ul>
148
    <li>Candy.</li>
149
    <li>Gum.</li>
150
    <li>Booze.</li>
151
    </ul>
152
153
Ordered (numbered) lists use regular numbers, followed by periods, as
154
list markers:
155
156
    1.  Red
157
    2.  Green
158
    3.  Blue
159
160
Output:
161
162
    <ol>
163
    <li>Red</li>
164
    <li>Green</li>
165
    <li>Blue</li>
166
    </ol>
167
168
If you put blank lines between items, you'll get `<p>` tags for the
169
list item text. You can create multi-paragraph list items by indenting
170
the paragraphs by 4 spaces or 1 tab:
171
172
    *   A list item.
173
    
174
        With multiple paragraphs.
175
176
    *   Another item in the list.
177
178
Output:
179
180
    <ul>
181
    <li><p>A list item.</p>
182
    <p>With multiple paragraphs.</p></li>
183
    <li><p>Another item in the list.</p></li>
184
    </ul>
185
    
186
187
188
### Links ###
189
190
Markdown supports two styles for creating links: *inline* and
191
*reference*. With both styles, you use square brackets to delimit the
192
text you want to turn into a link.
193
194
Inline-style links use parentheses immediately after the link text.
195
For example:
196
197
    This is an [example link](http://example.com/).
198
199
Output:
200
201
    <p>This is an <a href="http://example.com/">
202
    example link</a>.</p>
203
204
Optionally, you may include a title attribute in the parentheses:
205
206
    This is an [example link](http://example.com/ "With a Title").
207
208
Output:
209
210
    <p>This is an <a href="http://example.com/" title="With a Title">
211
    example link</a>.</p>
212
213
Reference-style links allow you to refer to your links by names, which
214
you define elsewhere in your document:
215
216
    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
223
Output:
224
225
    <p>I get 10 times more traffic from <a href="http://google.com/"
226
    title="Google">Google</a> than from <a href="http://search.yahoo.com/"
227
    title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
228
    title="MSN Search">MSN</a>.</p>
229
230
The title attribute is optional. Link names may contain letters,
231
numbers and spaces, but are *not* case sensitive:
232
233
    I start my morning with a cup of coffee and
234
    [The New York Times][NY Times].
235
236
    [ny times]: http://www.nytimes.com/
237
238
Output:
239
240
    <p>I start my morning with a cup of coffee and
241
    <a href="http://www.nytimes.com/">The New York Times</a>.</p>
242
243
244
### Images ###
245
246
Image syntax is very much like link syntax.
247
248
Inline (titles are optional):
249
250
    ![alt text](/path/to/img.jpg "Title")
251
252
Reference-style:
253
254
    ![alt text][id]
255
256
    [id]: /path/to/img.jpg "Title"
257
258
Both of the above examples produce the same output:
259
260
    <img src="/path/to/img.jpg" alt="alt text" title="Title" />
261
262
263
264
### Code ###
265
266
In a regular paragraph, you can create code span by wrapping text in
267
backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
268
`>`) will automatically be translated into HTML entities. This makes
269
it easy to use Markdown to write about HTML example code:
270
271
    I strongly recommend against using any `<blink>` tags.
272
273
    I wish SmartyPants used named entities like `&mdash;`
274
    instead of decimal-encoded entites like `&#8212;`.
275
276
Output:
277
278
    <p>I strongly recommend against using any
279
    <code>&lt;blink&gt;</code> tags.</p>
280
    
281
    <p>I wish SmartyPants used named entities like
282
    <code>&amp;mdash;</code> instead of decimal-encoded
283
    entites like <code>&amp;#8212;</code>.</p>
284
285
286
To specify an entire block of pre-formatted code, indent every line of
287
the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
288
and `>` characters will be escaped automatically.
289
290
Markdown:
291
292
    If you want your page to validate under XHTML 1.0 Strict,
293
    you've got to put paragraph tags in your blockquotes:
294
295
        <blockquote>
296
            <p>For example.</p>
297
        </blockquote>
298
299
Output:
300
301
    <p>If you want your page to validate under XHTML 1.0 Strict,
302
    you've got to put paragraph tags in your blockquotes:</p>
303
    
304
    <pre><code>&lt;blockquote&gt;
305
        &lt;p&gt;For example.&lt;/p&gt;
306
    &lt;/blockquote&gt;
307
    </code></pre>
308

You might want to use the Github-Flavored Markdown mode instead, which adds support for fenced code blocks and a few other things.

Optionally depends on the XML mode for properly highlighted inline XML blocks.

MIME types defined: text/x-markdown.

Parsing/Highlighting Tests: normal, verbose.