maruku 0.5.0 → 0.5.1
Sign up to get free protection for your applications and to get access to all the features.
- data/docs/changelog.html +65 -6
- data/docs/changelog.md +31 -1
- data/docs/entity_test.html +17 -17
- data/docs/exd.html +46 -8
- data/docs/index.html +58 -31
- data/docs/markdown_syntax.html +170 -6
- data/docs/maruku.html +58 -31
- data/docs/maruku.md +9 -16
- data/docs/math.md +76 -25
- data/docs/proposal.html +65 -9
- data/lib/maruku/ext/diagrams/layout.rb +405 -2
- data/lib/maruku/ext/diagrams/to_latex.rb +0 -205
- data/lib/maruku/ext/math/to_html.rb +0 -8
- data/lib/maruku/input/charsource.rb +5 -4
- data/lib/maruku/input/parse_doc.rb +1 -0
- data/lib/maruku/input/parse_span_better.rb +7 -2
- data/lib/maruku/output/to_html.rb +50 -7
- data/lib/maruku/output/to_latex.rb +6 -2
- data/lib/maruku/output/to_latex_entities.rb +3 -3
- data/lib/maruku/version.rb +1 -1
- data/tests/unittest/attributes/attributes.md +8 -49
- data/tests/unittest/blanks_in_code.md +6 -0
- data/tests/unittest/code.md +2 -0
- data/tests/unittest/code2.md +3 -1
- data/tests/unittest/code3.md +8 -0
- data/tests/unittest/email.md +2 -2
- data/tests/unittest/entities.md +2 -0
- data/tests/unittest/ie.md +112 -0
- data/tests/unittest/images.md +2 -2
- data/tests/unittest/images2.md +55 -0
- data/tests/unittest/inline_html.md +4 -0
- data/tests/unittest/links.md +1 -1
- data/tests/unittest/list3.md +3 -1
- data/tests/unittest/misc_sw.md +3 -1
- data/tests/unittest/smartypants.md +8 -0
- data/tests/unittest/syntax_hl.md +7 -1
- data/tests/unittest/test.md +2 -0
- metadata +4 -3
- data/docs/a.md +0 -4
data/docs/index.html
CHANGED
@@ -13,10 +13,12 @@
|
|
13
13
|
<p><a href='http://maruku.rubyforge.org/'>Maruku</a> is a Markdown interpreter written in <a href='http://www.ruby-lang.org'>Ruby</a>.</p>
|
14
14
|
|
15
15
|
<blockquote id='news'>
|
16
|
-
<p><a href='#release_notes'>Last release</a> is version 0.5.
|
16
|
+
<p><a href='#release_notes'>Last release</a> is version 0.5.1 – 2007-01-24.</p>
|
17
17
|
|
18
18
|
<p>Use this command to update:</p>
|
19
|
-
|
19
|
+
|
20
|
+
<pre><code>$ gem update maruku</code></pre>
|
21
|
+
</blockquote>
|
20
22
|
<hr />
|
21
23
|
<p>Maruku allows you to write in an easy-to-read-and-write syntax, like this:</p>
|
22
24
|
|
@@ -73,13 +75,15 @@
|
|
73
75
|
<p>The development site is <a href='http://rubyforge.org/projects/maruku/'>http://rubyforge.org/projects/maruku/</a>.</p>
|
74
76
|
|
75
77
|
<p>Install with:</p>
|
76
|
-
|
77
|
-
</code></pre>
|
78
|
+
|
79
|
+
<pre style='background-color: #efefff;'><code class='sh' lang='sh'>$ gem install maruku</code></pre>
|
80
|
+
|
78
81
|
<p>Released files can also be seen at <a href='http://rubyforge.org/frs/?group_id=2795'>http://rubyforge.org/frs/?group_id=2795</a>.</p>
|
79
82
|
|
80
83
|
<p>Anonymous access to the repository is possible with:</p>
|
81
|
-
|
82
|
-
</code></pre>
|
84
|
+
|
85
|
+
<pre style='background-color: #efefff;'><code class='sh' lang='sh'>$ svn checkout svn://rubyforge.org/var/svn/maruku/trunk</code></pre>
|
86
|
+
|
83
87
|
<p>If you want commit access to the repository, just create an account on Rubyforge and <a href='http://www.dis.uniroma1.it/~acensi/contact.html'>drop me a mail</a>.</p>
|
84
88
|
|
85
89
|
<h3 id='bugs_report'><span class='maruku_section_number'>2.1. </span>Bugs report</h3>
|
@@ -91,26 +95,33 @@
|
|
91
95
|
<h3 id='embedded_maruku'><span class='maruku_section_number'>3.1. </span>Embedded Maruku</h3>
|
92
96
|
|
93
97
|
<p>This is the basic usage:</p>
|
94
|
-
<pre><code>require 'rubygems'
|
95
|
-
require 'maruku'
|
96
98
|
|
97
|
-
|
98
|
-
|
99
|
-
|
99
|
+
<pre style='background-color: #efffef;'><code class='ruby' lang='ruby'><span class='ident'>require</span> <span class='punct'>'</span><span class='string'>rubygems</span><span class='punct'>'</span>
|
100
|
+
<span class='ident'>require</span> <span class='punct'>'</span><span class='string'>maruku</span><span class='punct'>'</span>
|
101
|
+
|
102
|
+
<span class='ident'>doc</span> <span class='punct'>=</span> <span class='constant'>Maruku</span><span class='punct'>.</span><span class='ident'>new</span><span class='punct'>(</span><span class='ident'>markdown_string</span><span class='punct'>)</span>
|
103
|
+
<span class='ident'>puts</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html</span></code></pre>
|
104
|
+
|
100
105
|
<p>The method <code>to_html</code> outputs only an HTML fragment, while the method <code>to_html_document</code> outputs a complete XHTML 1.0 document:</p>
|
101
|
-
|
102
|
-
</code></pre>
|
106
|
+
|
107
|
+
<pre style='background-color: #efffef;'><code class='ruby' lang='ruby'><span class='ident'>puts</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html_document</span></code></pre>
|
108
|
+
|
103
109
|
<p>You can have the REXML document tree with:</p>
|
104
|
-
|
105
|
-
</code></pre>
|
110
|
+
|
111
|
+
<pre style='background-color: #efffef;'><code class='ruby' lang='ruby'><span class='ident'>tree</span> <span class='punct'>=</span> <span class='ident'>doc</span><span class='punct'>.</span><span class='ident'>to_html_document_tree</span></code></pre>
|
112
|
+
|
106
113
|
<h3 id='from_the_command_line'><span class='maruku_section_number'>3.2. </span>From the command line</h3>
|
107
114
|
|
108
115
|
<p>There is one command-line program installed: <code>maruku</code>.</p>
|
109
116
|
|
110
117
|
<p>Without arguments, it converts Markdown to HTML:</p>
|
111
|
-
|
118
|
+
|
119
|
+
<pre style='background-color: #efefff;'><code class='sh' lang='sh'>$ maruku file.md # creates file.html</code></pre>
|
120
|
+
|
112
121
|
<p>With the <code>--pdf</code> arguments, it converts Markdown to LaTeX, then calls <code>pdflatex</code> to transform to PDF:</p>
|
113
|
-
|
122
|
+
|
123
|
+
<pre style='background-color: #efefff;'><code class='sh' lang='sh'>$ maruku --pdf file.md # creates file.tex and file.pdf</code></pre>
|
124
|
+
|
114
125
|
<h2 id='maruku-and-bluecloth'><span class='maruku_section_number'>4. </span>Maruku and Bluecloth</h2>
|
115
126
|
|
116
127
|
<p>The other Ruby implementation of Markdown is <a href='http://www.deveiate.org/projects/BlueCloth'>Bluecloth</a>.</p>
|
@@ -120,10 +131,12 @@ puts doc.to_html
|
|
120
131
|
<p>Maruku is usually faster than Bluecloth. Bluecloth is faster for very small documents. Bluecloth sometimes chokes on very big documents (it is reported that the blame should be on Ruby’s regexp implementation).</p>
|
121
132
|
|
122
133
|
<p>This is the canonical benchmark (the Markdown specification), executed with Ruby 1.8.5 on a Powerbook 1.5GhZ:</p>
|
134
|
+
|
123
135
|
<pre><code>BlueCloth (to_html): parsing 0.01 sec + rendering 1.87 sec = 1.88 sec (1.00x)
|
124
136
|
Maruku (to_html): parsing 0.66 sec + rendering 0.43 sec = 1.09 sec (1.73x)
|
125
137
|
Maruku (to_latex): parsing 0.67 sec + rendering 0.23 sec = 0.90 sec (2.10x)
|
126
138
|
</code></pre>
|
139
|
+
|
127
140
|
<p>Please note that Maruku has a lot more features and therefore is looking for much more patterns in the file.</p>
|
128
141
|
|
129
142
|
<h2 id='maruku_summary_of_features'><span class='maruku_section_number'>5. </span>Maruku summary of features</h2>
|
@@ -201,14 +214,16 @@ puts doc.to_html
|
|
201
214
|
<p>See the <a href='exd.html'>documentation for supported attributes</a>.</p>
|
202
215
|
|
203
216
|
<p>Meta-data for the document itself is specified through the use of email headers:</p>
|
204
|
-
|
217
|
+
|
218
|
+
<pre style='background-color: #ffefef;'><code>Title: A simple document containing meta-headers
|
205
219
|
CSS: style.css
|
206
220
|
|
207
|
-
Content of the document
|
208
|
-
|
221
|
+
Content of the document</code></pre>
|
222
|
+
|
209
223
|
<p>When creating the document through</p>
|
210
|
-
|
211
|
-
</code></pre>
|
224
|
+
|
225
|
+
<pre style='background-color: #efffef;'><code class='ruby' lang='ruby'><span class='constant'>Maruku</span><span class='punct'>.</span><span class='ident'>new</span><span class='punct'>(</span><span class='ident'>s</span><span class='punct'>).</span><span class='ident'>to_html_document</span></code></pre>
|
226
|
+
|
212
227
|
<p>the title and stylesheet are added as expected.</p>
|
213
228
|
|
214
229
|
<p>Meta-data keys are assumed to be case-insensitive.</p>
|
@@ -216,9 +231,11 @@ Content of the document
|
|
216
231
|
<h3 id='toc-generation'><span class='maruku_section_number'>5.2. </span>Automatic generation of the table of contents</h3>
|
217
232
|
|
218
233
|
<p>If you create a list, and then set the <code>toc</code> attribute, when rendering Maruku will create an auto-generated table of contents.</p>
|
234
|
+
|
219
235
|
<pre><code>* This will become a table of contents (this text will be scraped).
|
220
236
|
{:toc}
|
221
237
|
</code></pre>
|
238
|
+
|
222
239
|
<p>You can see an example of this at the beginning of this document.</p>
|
223
240
|
|
224
241
|
<h3 id='entities'><span class='maruku_section_number'>5.3. </span>Use HTML entities</h3>
|
@@ -242,37 +259,47 @@ Content of the document
|
|
242
259
|
<ul>
|
243
260
|
<li>
|
244
261
|
<p>tables</p>
|
245
|
-
|
262
|
+
|
263
|
+
<pre style='background-color: #ffefef;'><code>Col1 | Very very long head | Very very long head|
|
246
264
|
-----|:-------------------:|-------------------:|
|
247
|
-
cell | center-align | right-align |</code></pre
|
265
|
+
cell | center-align | right-align |</code></pre>
|
266
|
+
<table><thead><tr><th>Col1</th><th>Very very long head</th><th>Very very long head</th></tr></thead><tbody><tr><td style='text-align: left;'>cell</td><td style='text-align: center;'>center-align</td><td style='text-align: right;'>right-align</td>
|
248
267
|
</tr></tbody></table></li>
|
249
268
|
|
250
269
|
<li>
|
251
270
|
<p>footnotes <sup id='fnref:1'><a href='#fn:1' rel='footnote'>1</a></sup></p>
|
252
|
-
<pre><code>* footnotes [^foot]
|
253
271
|
|
254
|
-
[^foot]
|
272
|
+
<pre style='background-color: #ffefef;'><code>* footnotes [^foot]
|
273
|
+
|
274
|
+
[^foot]: I really was missing those.</code></pre>
|
275
|
+
</li>
|
255
276
|
</ul>
|
256
277
|
|
257
278
|
<ul>
|
258
279
|
<li>
|
259
280
|
<p>Markdown inside HTML elements</p>
|
260
|
-
|
281
|
+
|
282
|
+
<pre><code class='xml' lang='xml'><span class='punct'><</span><span class='tag'>div</span> <span class='attribute'>markdown</span><span class='punct'>="</span><span class='string'>1</span><span class='punct'>"</span> <span class='attribute'>style</span><span class='punct'>="</span><span class='string'>border: solid 1px black</span><span class='punct'>"></span>
|
261
283
|
This is a div with Markdown **strong text**
|
262
|
-
|
284
|
+
<span class='punct'></</span><span class='tag'>div</span><span class='punct'>></span></code></pre>
|
285
|
+
<div style='border: solid 1px black'>
|
263
286
|
<p>This is a div with Markdown <strong>strong text</strong></p>
|
264
287
|
</div></li>
|
265
288
|
|
266
289
|
<li>
|
267
290
|
<p>header ids</p>
|
268
|
-
|
291
|
+
|
292
|
+
<pre style='background-color: #ffefef;'><code>## Download ## {#download}</code></pre>
|
293
|
+
|
269
294
|
<p>For example, <a href='#download'>a link to the download</a> header.</p>
|
270
295
|
</li>
|
271
296
|
|
272
297
|
<li>
|
273
298
|
<p>definition lists</p>
|
274
|
-
|
299
|
+
|
300
|
+
<pre style='background-color: #ffefef;'><code>Definition list
|
275
301
|
: something very hard to parse</code></pre>
|
302
|
+
|
276
303
|
<dl>
|
277
304
|
<dt>Definition list</dt>
|
278
305
|
|
@@ -296,4 +323,4 @@ I would love to have an equivalent in Ruby.
|
|
296
323
|
|
297
324
|
--><div class='footnotes'><hr /><ol><li id='fn:1'>
|
298
325
|
<p>I really was missing those.</p>
|
299
|
-
<a href='#fnref:1' rev='footnote'>↩</a></li></ol></div><div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown-superset interpreter for Ruby'>Maruku</a> at
|
326
|
+
<a href='#fnref:1' rev='footnote'>↩</a></li></ol></div><div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown-superset interpreter for Ruby'>Maruku</a> at 13:51 on Wednesday, January 24th, 2007.</span></div></body></html>
|
data/docs/markdown_syntax.html
CHANGED
@@ -87,6 +87,7 @@
|
|
87
87
|
<p>The only restrictions are that block-level HTML elements – e.g. <code><div></code>, <code><table></code>, <code><pre></code>, <code><p></code>, etc. – must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <code><p></code> tags around HTML block-level tags.</p>
|
88
88
|
|
89
89
|
<p>For example, to add an HTML table to a Markdown article:</p>
|
90
|
+
|
90
91
|
<pre><code>This is a regular paragraph.
|
91
92
|
|
92
93
|
<table>
|
@@ -97,6 +98,7 @@
|
|
97
98
|
|
98
99
|
This is another regular paragraph.
|
99
100
|
</code></pre>
|
101
|
+
|
100
102
|
<p>Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style <code>*emphasis*</code> inside an HTML block.</p>
|
101
103
|
|
102
104
|
<p>Span-level HTML tags – e.g. <code><span></code>, <code><cite></code>, or <code><del></code> – can be used anywhere in a Markdown paragraph, list item, or header. If you want, you can even use HTML tags instead of Markdown formatting; e.g. if you’d prefer to use HTML <code><a></code> or <code><img></code> tags instead of Markdown’s link or image syntax, go right ahead.</p>
|
@@ -106,30 +108,44 @@ This is another regular paragraph.
|
|
106
108
|
<p>In HTML, there are two characters that demand special treatment: <code><</code> and <code>&</code>. Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you must escape them as entities, e.g. <code>&lt;</code>, and <code>&amp;</code>.</p>
|
107
109
|
|
108
110
|
<p>Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ’<code>AT&amp;T</code>’. You even need to escape ampersands within URLs. Thus, if you want to link to:</p>
|
111
|
+
|
109
112
|
<pre><code>http://images.google.com/images?num=30&q=larry+bird
|
110
113
|
</code></pre>
|
114
|
+
|
111
115
|
<p>you need to encode the URL as:</p>
|
116
|
+
|
112
117
|
<pre><code>http://images.google.com/images?num=30&amp;q=larry+bird
|
113
118
|
</code></pre>
|
119
|
+
|
114
120
|
<p>in your anchor tag <code>href</code> attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.</p>
|
115
121
|
|
116
122
|
<p>Markdown allows you to use these characters naturally, taking care of all the necessary escaping for you. If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into <code>&amp;</code>.</p>
|
117
123
|
|
118
124
|
<p>So, if you want to include a copyright symbol in your article, you can write:</p>
|
125
|
+
|
119
126
|
<pre><code>&copy;
|
120
127
|
</code></pre>
|
128
|
+
|
121
129
|
<p>and Markdown will leave it alone. But if you write:</p>
|
130
|
+
|
122
131
|
<pre><code>AT&T
|
123
132
|
</code></pre>
|
133
|
+
|
124
134
|
<p>Markdown will translate it to:</p>
|
135
|
+
|
125
136
|
<pre><code>AT&amp;T
|
126
137
|
</code></pre>
|
138
|
+
|
127
139
|
<p>Similarly, because Markdown supports <a href='#html'>inline HTML</a>, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:</p>
|
140
|
+
|
128
141
|
<pre><code>4 < 5
|
129
142
|
</code></pre>
|
143
|
+
|
130
144
|
<p>Markdown will translate it to:</p>
|
145
|
+
|
131
146
|
<pre><code>4 &lt; 5
|
132
147
|
</code></pre>
|
148
|
+
|
133
149
|
<p>However, inside Markdown code spans and blocks, angle brackets and ampersands are <em>always</em> encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single <code><</code> and <code>&</code> in your example code needs to be escaped.)</p>
|
134
150
|
<hr /><h2 id='block'>Block Elements</h2><h3 id='p'>Paragraphs and Line Breaks</h3>
|
135
151
|
<p>A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line – a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.</p>
|
@@ -143,30 +159,37 @@ This is another regular paragraph.
|
|
143
159
|
<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>
|
144
160
|
|
145
161
|
<p>Setext-style headers are “underlined” using equal signs (for first-level headers) and dashes (for second-level headers). For example:</p>
|
162
|
+
|
146
163
|
<pre><code>This is an H1
|
147
164
|
=============
|
148
165
|
|
149
166
|
This is an H2
|
150
167
|
-------------
|
151
168
|
</code></pre>
|
169
|
+
|
152
170
|
<p>Any number of underlining <code>=</code>’s or <code>-</code>’s will work.</p>
|
153
171
|
|
154
172
|
<p>Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:</p>
|
173
|
+
|
155
174
|
<pre><code># This is an H1
|
156
175
|
|
157
176
|
## This is an H2
|
158
177
|
|
159
178
|
###### This is an H6
|
160
179
|
</code></pre>
|
180
|
+
|
161
181
|
<p>Optionally, you may “close” atx-style headers. This is purely cosmetic – you can use this if you think it looks better. The closing hashes don’t even need to match the number of hashes used to open the header. (The number of opening hashes determines the header level.) :</p>
|
182
|
+
|
162
183
|
<pre><code># This is an H1 #
|
163
184
|
|
164
185
|
## This is an H2 ##
|
165
186
|
|
166
187
|
### This is an H3 ######
|
167
188
|
|
168
|
-
</code></pre
|
189
|
+
</code></pre>
|
190
|
+
<h3 id='blockquote'>Blockquotes</h3>
|
169
191
|
<p>Markdown uses email-style <code>></code> characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a <code>></code> before every line:</p>
|
192
|
+
|
170
193
|
<pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
171
194
|
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
172
195
|
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
@@ -174,7 +197,9 @@ This is an H2
|
|
174
197
|
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
175
198
|
> id sem consectetuer libero luctus adipiscing.
|
176
199
|
</code></pre>
|
200
|
+
|
177
201
|
<p>Markdown allows you to be lazy and only put the <code>></code> before the first line of a hard-wrapped paragraph:</p>
|
202
|
+
|
178
203
|
<pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
179
204
|
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
180
205
|
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
@@ -182,14 +207,18 @@ Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
|
182
207
|
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
183
208
|
id sem consectetuer libero luctus adipiscing.
|
184
209
|
</code></pre>
|
210
|
+
|
185
211
|
<p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of <code>></code>:</p>
|
212
|
+
|
186
213
|
<pre><code>> This is the first level of quoting.
|
187
214
|
>
|
188
215
|
> > This is nested blockquote.
|
189
216
|
>
|
190
217
|
> Back to the first level.
|
191
218
|
</code></pre>
|
219
|
+
|
192
220
|
<p>Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:</p>
|
221
|
+
|
193
222
|
<pre><code>> ## This is a header.
|
194
223
|
>
|
195
224
|
> 1. This is the first list item.
|
@@ -199,47 +228,62 @@ id sem consectetuer libero luctus adipiscing.
|
|
199
228
|
>
|
200
229
|
> return shell_exec("echo $input | $markdown_script");
|
201
230
|
</code></pre>
|
231
|
+
|
202
232
|
<p>Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.</p>
|
203
233
|
<h3 id='list'>Lists</h3>
|
204
234
|
<p>Markdown supports ordered (numbered) and unordered (bulleted) lists.</p>
|
205
235
|
|
206
236
|
<p>Unordered lists use asterisks, pluses, and hyphens – interchangably – as list markers:</p>
|
237
|
+
|
207
238
|
<pre><code>* Red
|
208
239
|
* Green
|
209
240
|
* Blue
|
210
241
|
</code></pre>
|
242
|
+
|
211
243
|
<p>is equivalent to:</p>
|
244
|
+
|
212
245
|
<pre><code>+ Red
|
213
246
|
+ Green
|
214
247
|
+ Blue
|
215
248
|
</code></pre>
|
249
|
+
|
216
250
|
<p>and:</p>
|
251
|
+
|
217
252
|
<pre><code>- Red
|
218
253
|
- Green
|
219
254
|
- Blue
|
220
255
|
</code></pre>
|
256
|
+
|
221
257
|
<p>Ordered lists use numbers followed by periods:</p>
|
258
|
+
|
222
259
|
<pre><code>1. Bird
|
223
260
|
2. McHale
|
224
261
|
3. Parish
|
225
262
|
</code></pre>
|
263
|
+
|
226
264
|
<p>It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:</p>
|
265
|
+
|
227
266
|
<pre><code><ol>
|
228
267
|
<li>Bird</li>
|
229
268
|
<li>McHale</li>
|
230
269
|
<li>Parish</li>
|
231
270
|
</ol>
|
232
271
|
</code></pre>
|
272
|
+
|
233
273
|
<p>If you instead wrote the list in Markdown like this:</p>
|
274
|
+
|
234
275
|
<pre><code>1. Bird
|
235
276
|
1. McHale
|
236
277
|
1. Parish
|
237
278
|
</code></pre>
|
279
|
+
|
238
280
|
<p>or even:</p>
|
281
|
+
|
239
282
|
<pre><code>3. Bird
|
240
283
|
1. McHale
|
241
284
|
8. Parish
|
242
285
|
</code></pre>
|
286
|
+
|
243
287
|
<p>you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.</p>
|
244
288
|
|
245
289
|
<p>If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.</p>
|
@@ -247,41 +291,54 @@ id sem consectetuer libero luctus adipiscing.
|
|
247
291
|
<p>List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.</p>
|
248
292
|
|
249
293
|
<p>To make lists look nice, you can wrap items with hanging indents:</p>
|
294
|
+
|
250
295
|
<pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
251
296
|
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
252
297
|
viverra nec, fringilla in, laoreet vitae, risus.
|
253
298
|
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
254
299
|
Suspendisse id sem consectetuer libero luctus adipiscing.
|
255
300
|
</code></pre>
|
301
|
+
|
256
302
|
<p>But if you want to be lazy, you don’t have to:</p>
|
303
|
+
|
257
304
|
<pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
258
305
|
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
259
306
|
viverra nec, fringilla in, laoreet vitae, risus.
|
260
307
|
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
261
308
|
Suspendisse id sem consectetuer libero luctus adipiscing.
|
262
309
|
</code></pre>
|
310
|
+
|
263
311
|
<p>If list items are separated by blank lines, Markdown will wrap the items in <code><p></code> tags in the HTML output. For example, this input:</p>
|
312
|
+
|
264
313
|
<pre><code>* Bird
|
265
314
|
* Magic
|
266
315
|
</code></pre>
|
316
|
+
|
267
317
|
<p>will turn into:</p>
|
318
|
+
|
268
319
|
<pre><code><ul>
|
269
320
|
<li>Bird</li>
|
270
321
|
<li>Magic</li>
|
271
322
|
</ul>
|
272
323
|
</code></pre>
|
324
|
+
|
273
325
|
<p>But this:</p>
|
326
|
+
|
274
327
|
<pre><code>* Bird
|
275
328
|
|
276
329
|
* Magic
|
277
330
|
</code></pre>
|
331
|
+
|
278
332
|
<p>will turn into:</p>
|
333
|
+
|
279
334
|
<pre><code><ul>
|
280
335
|
<li><p>Bird</p></li>
|
281
336
|
<li><p>Magic</p></li>
|
282
337
|
</ul>
|
283
338
|
</code></pre>
|
339
|
+
|
284
340
|
<p>List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be intended by either 4 spaces or one tab:</p>
|
341
|
+
|
285
342
|
<pre><code>1. This is a list item with two paragraphs. Lorem ipsum dolor
|
286
343
|
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
|
287
344
|
mi posuere lectus.
|
@@ -292,7 +349,9 @@ Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
292
349
|
|
293
350
|
2. Suspendisse id sem consectetuer libero luctus adipiscing.
|
294
351
|
</code></pre>
|
352
|
+
|
295
353
|
<p>It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:</p>
|
354
|
+
|
296
355
|
<pre><code>* This is a list item with two paragraphs.
|
297
356
|
|
298
357
|
This is the second paragraph in the list item. You're
|
@@ -301,47 +360,63 @@ sit amet, consectetuer adipiscing elit.
|
|
301
360
|
|
302
361
|
* Another item in the same list.
|
303
362
|
</code></pre>
|
363
|
+
|
304
364
|
<p>To put a blockquote within a list item, the blockquote’s <code>></code> delimiters need to be indented:</p>
|
365
|
+
|
305
366
|
<pre><code>* A list item with a blockquote:
|
306
367
|
|
307
368
|
> This is a blockquote
|
308
369
|
> inside a list item.
|
309
370
|
</code></pre>
|
371
|
+
|
310
372
|
<p>To put a code block within a list item, the code block needs to be indented <em>twice</em> – 8 spaces or two tabs:</p>
|
373
|
+
|
311
374
|
<pre><code>* A list item with a code block:
|
312
375
|
|
313
376
|
<code goes here>
|
314
377
|
|
315
378
|
</code></pre>
|
379
|
+
|
316
380
|
<p>It’s worth noting that it’s possible to trigger an ordered list by accident, by writing something like this:</p>
|
381
|
+
|
317
382
|
<pre><code>1986. What a great season.
|
318
383
|
</code></pre>
|
384
|
+
|
319
385
|
<p>In other words, a <em>number-period-space</em> sequence at the beginning of a line. To avoid this, you can backslash-escape the period:</p>
|
386
|
+
|
320
387
|
<pre><code>1986\. What a great season.
|
321
388
|
|
322
389
|
|
323
|
-
</code></pre
|
390
|
+
</code></pre>
|
391
|
+
<h3 id='precode'>Code Blocks</h3>
|
324
392
|
<p>Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both <code><pre></code> and <code><code></code> tags.</p>
|
325
393
|
|
326
394
|
<p>To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:</p>
|
395
|
+
|
327
396
|
<pre><code>This is a normal paragraph:
|
328
397
|
|
329
398
|
This is a code block.
|
330
399
|
</code></pre>
|
400
|
+
|
331
401
|
<p>Markdown will generate:</p>
|
402
|
+
|
332
403
|
<pre><code><p>This is a normal paragraph:</p>
|
333
404
|
|
334
405
|
<pre><code>This is a code block.
|
335
406
|
</code></pre>
|
336
407
|
</code></pre>
|
408
|
+
|
337
409
|
<p>One level of indentation – 4 spaces or 1 tab – is removed from each line of the code block. For example, this:</p>
|
410
|
+
|
338
411
|
<pre><code>Here is an example of AppleScript:
|
339
412
|
|
340
413
|
tell application "Foo"
|
341
414
|
beep
|
342
415
|
end tell
|
343
416
|
</code></pre>
|
417
|
+
|
344
418
|
<p>will turn into:</p>
|
419
|
+
|
345
420
|
<pre><code><p>Here is an example of AppleScript:</p>
|
346
421
|
|
347
422
|
<pre><code>tell application "Foo"
|
@@ -349,22 +424,28 @@ sit amet, consectetuer adipiscing elit.
|
|
349
424
|
end tell
|
350
425
|
</code></pre>
|
351
426
|
</code></pre>
|
427
|
+
|
352
428
|
<p>A code block continues until it reaches a line that is not indented (or the end of the article).</p>
|
353
429
|
|
354
430
|
<p>Within a code block, ampersands (<code>&</code>) and angle brackets (<code><</code> and <code>></code>) are automatically converted into HTML entities. This makes it very easy to include example HTML source code using Markdown – just paste it and indent it, and Markdown will handle the hassle of encoding the ampersands and angle brackets. For example, this:</p>
|
431
|
+
|
355
432
|
<pre><code> <div class="footer">
|
356
433
|
&copy; 2004 Foo Corporation
|
357
434
|
</div>
|
358
435
|
</code></pre>
|
436
|
+
|
359
437
|
<p>will turn into:</p>
|
438
|
+
|
360
439
|
<pre><code><pre><code>&lt;div class="footer"&gt;
|
361
440
|
&amp;copy; 2004 Foo Corporation
|
362
441
|
&lt;/div&gt;
|
363
442
|
</code></pre>
|
364
443
|
</code></pre>
|
444
|
+
|
365
445
|
<p>Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use Markdown to write about Markdown’s own syntax.</p>
|
366
446
|
<h3 id='hr'>Horizontal Rules</h3>
|
367
447
|
<p>You can produce a horizontal rule tag (<code><hr /></code>) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:</p>
|
448
|
+
|
368
449
|
<pre><code>* * *
|
369
450
|
|
370
451
|
***
|
@@ -375,35 +456,48 @@ end tell
|
|
375
456
|
|
376
457
|
---------------------------------------
|
377
458
|
|
378
|
-
</code></pre
|
459
|
+
</code></pre>
|
460
|
+
<hr /><h2 id='span'>Span Elements</h2><h3 id='link'>Links</h3>
|
379
461
|
<p>Markdown supports two style of links: <em>inline</em> and <em>reference</em>.</p>
|
380
462
|
|
381
463
|
<p>In both styles, the link text is delimited by <span>square brackets</span>.</p>
|
382
464
|
|
383
465
|
<p>To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an <em>optional</em> title for the link, surrounded in quotes. For example:</p>
|
466
|
+
|
384
467
|
<pre><code>This is [an example](http://example.com/ "Title") inline link.
|
385
468
|
|
386
469
|
[This link](http://example.net/) has no title attribute.
|
387
470
|
</code></pre>
|
471
|
+
|
388
472
|
<p>Will produce:</p>
|
473
|
+
|
389
474
|
<pre><code><p>This is <a href="http://example.com/" title="Title">
|
390
475
|
an example</a> inline link.</p>
|
391
476
|
|
392
477
|
<p><a href="http://example.net/">This link</a> has no
|
393
478
|
title attribute.</p>
|
394
479
|
</code></pre>
|
480
|
+
|
395
481
|
<p>If you’re referring to a local resource on the same server, you can use relative paths:</p>
|
482
|
+
|
396
483
|
<pre><code>See my [About](/about/) page for details.
|
397
484
|
</code></pre>
|
485
|
+
|
398
486
|
<p>Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:</p>
|
487
|
+
|
399
488
|
<pre><code>This is [an example][id] reference-style link.
|
400
489
|
</code></pre>
|
490
|
+
|
401
491
|
<p>You can optionally use a space to separate the sets of brackets:</p>
|
492
|
+
|
402
493
|
<pre><code>This is [an example] [id] reference-style link.
|
403
494
|
</code></pre>
|
495
|
+
|
404
496
|
<p>Then, anywhere in the document, you define your link label like this, on a line by itself:</p>
|
497
|
+
|
405
498
|
<pre><code>[id]: http://example.com/ "Optional Title Here"
|
406
499
|
</code></pre>
|
500
|
+
|
407
501
|
<p>That is:</p>
|
408
502
|
|
409
503
|
<ul>
|
@@ -419,42 +513,59 @@ title attribute.</p>
|
|
419
513
|
</ul>
|
420
514
|
|
421
515
|
<p>The following three link definitions are equivalent:</p>
|
516
|
+
|
422
517
|
<pre><code>[foo]: http://example.com/ "Optional Title Here"
|
423
518
|
[foo]: http://example.com/ 'Optional Title Here'
|
424
519
|
[foo]: http://example.com/ (Optional Title Here)
|
425
520
|
</code></pre>
|
521
|
+
|
426
522
|
<p><strong>Note:</strong> There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.</p>
|
427
523
|
|
428
524
|
<p>The link URL may, optionally, be surrounded by angle brackets:</p>
|
525
|
+
|
429
526
|
<pre><code>[id]: <http://example.com/> "Optional Title Here"
|
430
527
|
</code></pre>
|
528
|
+
|
431
529
|
<p>You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:</p>
|
530
|
+
|
432
531
|
<pre><code>[id]: http://example.com/longish/path/to/resource/here
|
433
532
|
"Optional Title Here"
|
434
533
|
</code></pre>
|
534
|
+
|
435
535
|
<p>Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.</p>
|
436
536
|
|
437
537
|
<p>Link definition names may constist of letters, numbers, spaces, and punctuation – but they are <em>not</em> case sensitive. E.g. these two links:</p>
|
538
|
+
|
438
539
|
<pre><code>[link text][a]
|
439
540
|
[link text][A]
|
440
541
|
</code></pre>
|
542
|
+
|
441
543
|
<p>are equivalent.</p>
|
442
544
|
|
443
545
|
<p>The <em>implicit link name</em> shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets – e.g., to link the word “Google” to the google.com web site, you could simply write:</p>
|
546
|
+
|
444
547
|
<pre><code>[Google][]
|
445
548
|
</code></pre>
|
549
|
+
|
446
550
|
<p>And then define the link:</p>
|
551
|
+
|
447
552
|
<pre><code>[Google]: http://google.com/
|
448
553
|
</code></pre>
|
554
|
+
|
449
555
|
<p>Because link names may contain spaces, this shortcut even works for multiple words in the link text:</p>
|
556
|
+
|
450
557
|
<pre><code>Visit [Daring Fireball][] for more information.
|
451
558
|
</code></pre>
|
559
|
+
|
452
560
|
<p>And then define the link:</p>
|
561
|
+
|
453
562
|
<pre><code>[Daring Fireball]: http://daringfireball.net/
|
454
563
|
</code></pre>
|
564
|
+
|
455
565
|
<p>Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they’re used, but if you want, you can put them all at the end of your document, sort of like footnotes.</p>
|
456
566
|
|
457
567
|
<p>Here’s an example of reference links in action:</p>
|
568
|
+
|
458
569
|
<pre><code>I get 10 times more traffic from [Google] [1] than from
|
459
570
|
[Yahoo] [2] or [MSN] [3].
|
460
571
|
|
@@ -462,7 +573,9 @@ title attribute.</p>
|
|
462
573
|
[2]: http://search.yahoo.com/ "Yahoo Search"
|
463
574
|
[3]: http://search.msn.com/ "MSN Search"
|
464
575
|
</code></pre>
|
576
|
+
|
465
577
|
<p>Using the implicit link name shortcut, you could instead write:</p>
|
578
|
+
|
466
579
|
<pre><code>I get 10 times more traffic from [Google][] than from
|
467
580
|
[Yahoo][] or [MSN][].
|
468
581
|
|
@@ -470,22 +583,28 @@ title attribute.</p>
|
|
470
583
|
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
|
471
584
|
[msn]: http://search.msn.com/ "MSN Search"
|
472
585
|
</code></pre>
|
586
|
+
|
473
587
|
<p>Both of the above examples will produce the following HTML output:</p>
|
588
|
+
|
474
589
|
<pre><code><p>I get 10 times more traffic from <a href="http://google.com/"
|
475
590
|
title="Google">Google</a> than from
|
476
591
|
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
|
477
592
|
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
|
478
593
|
</code></pre>
|
594
|
+
|
479
595
|
<p>For comparison, here is the same paragraph written using Markdown’s inline link style:</p>
|
596
|
+
|
480
597
|
<pre><code>I get 10 times more traffic from [Google](http://google.com/ "Google")
|
481
598
|
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
|
482
599
|
[MSN](http://search.msn.com/ "MSN Search").
|
483
600
|
</code></pre>
|
601
|
+
|
484
602
|
<p>The point of reference-style links is not that they’re easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it’s 176 characters; and as raw HTML, it’s 234 characters. In the raw HTML, there’s more markup than there is text.</p>
|
485
603
|
|
486
604
|
<p>With Markdown’s reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.</p>
|
487
605
|
<h3 id='em'>Emphasis</h3>
|
488
606
|
<p>Markdown treats asterisks (<code>*</code>) and underscores (<code>_</code>) as indicators of emphasis. Text wrapped with one <code>*</code> or <code>_</code> will be wrapped with an HTML <code><em></code> tag; double <code>*</code>’s or <code>_</code>’s will be wrapped with an HTML <code><strong></code> tag. E.g., this input:</p>
|
607
|
+
|
489
608
|
<pre><code>*single asterisks*
|
490
609
|
|
491
610
|
_single underscores_
|
@@ -494,7 +613,9 @@ _single underscores_
|
|
494
613
|
|
495
614
|
__double underscores__
|
496
615
|
</code></pre>
|
616
|
+
|
497
617
|
<p>will produce:</p>
|
618
|
+
|
498
619
|
<pre><code><em>single asterisks</em>
|
499
620
|
|
500
621
|
<em>single underscores</em>
|
@@ -503,64 +624,91 @@ __double underscores__
|
|
503
624
|
|
504
625
|
<strong>double underscores</strong>
|
505
626
|
</code></pre>
|
627
|
+
|
506
628
|
<p>You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.</p>
|
507
629
|
|
508
630
|
<p>Emphasis can be used in the middle of a word:</p>
|
631
|
+
|
509
632
|
<pre><code>un*fucking*believable
|
510
633
|
</code></pre>
|
634
|
+
|
511
635
|
<p>But if you surround an <code>*</code> or <code>_</code> with spaces, it’ll be treated as a literal asterisk or underscore.</p>
|
512
636
|
|
513
637
|
<p>To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:</p>
|
638
|
+
|
514
639
|
<pre><code>\*this text is surrounded by literal asterisks\*
|
515
640
|
|
516
641
|
|
517
|
-
</code></pre
|
642
|
+
</code></pre>
|
643
|
+
<h3 id='code'>Code</h3>
|
518
644
|
<p>To indicate a span of code, wrap it with backtick quotes (<code>`</code>). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:</p>
|
645
|
+
|
519
646
|
<pre><code>Use the `printf()` function.
|
520
647
|
</code></pre>
|
648
|
+
|
521
649
|
<p>will produce:</p>
|
650
|
+
|
522
651
|
<pre><code><p>Use the <code>printf()</code> function.</p>
|
523
652
|
</code></pre>
|
653
|
+
|
524
654
|
<p>To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:</p>
|
655
|
+
|
525
656
|
<pre><code>``There is a literal backtick (`) here.``
|
526
657
|
</code></pre>
|
658
|
+
|
527
659
|
<p>which will produce this:</p>
|
660
|
+
|
528
661
|
<pre><code><p><code>There is a literal backtick (`) here.</code></p>
|
529
662
|
</code></pre>
|
663
|
+
|
530
664
|
<p>The backtick delimiters surrounding a code span may include spaces – one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:</p>
|
665
|
+
|
531
666
|
<pre><code>A single backtick in a code span: `` ` ``
|
532
667
|
|
533
668
|
A backtick-delimited string in a code span: `` `foo` ``
|
534
669
|
</code></pre>
|
670
|
+
|
535
671
|
<p>will produce:</p>
|
672
|
+
|
536
673
|
<pre><code><p>A single backtick in a code span: <code>`</code></p>
|
537
674
|
|
538
675
|
<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
|
539
676
|
</code></pre>
|
677
|
+
|
540
678
|
<p>With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this:</p>
|
679
|
+
|
541
680
|
<pre><code>Please don't use any `<blink>` tags.
|
542
681
|
</code></pre>
|
682
|
+
|
543
683
|
<p>into:</p>
|
684
|
+
|
544
685
|
<pre><code><p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
|
545
686
|
</code></pre>
|
687
|
+
|
546
688
|
<p>You can write this:</p>
|
689
|
+
|
547
690
|
<pre><code>`&#8212;` is the decimal-encoded equivalent of `&mdash;`.
|
548
691
|
</code></pre>
|
692
|
+
|
549
693
|
<p>to produce:</p>
|
694
|
+
|
550
695
|
<pre><code><p><code>&amp;#8212;</code> is the decimal-encoded
|
551
696
|
equivalent of <code>&amp;mdash;</code>.</p>
|
552
697
|
|
553
698
|
|
554
|
-
</code></pre
|
699
|
+
</code></pre>
|
700
|
+
<h3 id='img'>Images</h3>
|
555
701
|
<p>Admittedly, it’s fairly difficult to devise a “natural” syntax for placing images into a plain text document format.</p>
|
556
702
|
|
557
703
|
<p>Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: <em>inline</em> and <em>reference</em>.</p>
|
558
704
|
|
559
705
|
<p>Inline image syntax looks like this:</p>
|
706
|
+
|
560
707
|
<pre><code>![Alt text](/path/to/img.jpg)
|
561
708
|
|
562
709
|
![Alt text](/path/to/img.jpg "Optional title")
|
563
710
|
</code></pre>
|
711
|
+
|
564
712
|
<p>That is:</p>
|
565
713
|
|
566
714
|
<ul>
|
@@ -572,35 +720,50 @@ equivalent of <code>&amp;mdash;</code>.</p>
|
|
572
720
|
</ul>
|
573
721
|
|
574
722
|
<p>Reference-style image syntax looks like this:</p>
|
723
|
+
|
575
724
|
<pre><code>![Alt text][id]
|
576
725
|
</code></pre>
|
726
|
+
|
577
727
|
<p>Where “id” is the name of a defined image reference. Image references are defined using syntax identical to link references:</p>
|
728
|
+
|
578
729
|
<pre><code>[id]: url/to/image "Optional title attribute"
|
579
730
|
</code></pre>
|
731
|
+
|
580
732
|
<p>As of this writing, Markdown has no syntax for specifying the dimensions of an image; if this is important to you, you can simply use regular HTML <code><img></code> tags.</p>
|
581
733
|
<hr /><h2 id='misc'>Miscellaneous</h2><h3 id='autolink'>Automatic Links</h3>
|
582
734
|
<p>Markdown supports a shortcut style for creating “automatic” links for URLs and 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 address, and also have it be a clickable link, you can do this:</p>
|
735
|
+
|
583
736
|
<pre><code><http://example.com/></code></pre>
|
737
|
+
|
584
738
|
<p>Markdown will turn this into:</p>
|
739
|
+
|
585
740
|
<pre><code><a href="http://example.com/">http://example.com/</a>
|
586
741
|
</code></pre>
|
742
|
+
|
587
743
|
<p>Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this:</p>
|
744
|
+
|
588
745
|
<pre><code><address@example.com>
|
589
746
|
</code></pre>
|
747
|
+
|
590
748
|
<p>into something like this:</p>
|
749
|
+
|
591
750
|
<pre><code><a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
|
592
751
|
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
|
593
752
|
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
|
594
753
|
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
|
595
754
|
</code></pre>
|
755
|
+
|
596
756
|
<p>which will render in a browser as a clickable link to “address@example.com”.</p>
|
597
757
|
|
598
758
|
<p>(This sort of entity-encoding trick will indeed fool many, if not most, address-harvesting bots, but it definitely won’t fool all of them. It’s better than nothing, but an address published in this way will probably eventually start receiving spam.)</p>
|
599
759
|
<h3 id='backslash'>Backslash Escapes</h3>
|
600
760
|
<p>Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML <code><em></code> tag), you can backslashes before the asterisks, like this:</p>
|
761
|
+
|
601
762
|
<pre><code>\*literal asterisks\*
|
602
763
|
</code></pre>
|
764
|
+
|
603
765
|
<p>Markdown provides backslash escapes for the following characters:</p>
|
766
|
+
|
604
767
|
<pre><code>\ backslash
|
605
768
|
` backtick
|
606
769
|
* asterisk
|
@@ -612,4 +775,5 @@ _ underscore
|
|
612
775
|
+ plus sign
|
613
776
|
- minus sign (hyphen)
|
614
777
|
. dot
|
615
|
-
! exclamation mark</code></pre
|
778
|
+
! exclamation mark</code></pre>
|
779
|
+
<div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown-superset interpreter for Ruby'>Maruku</a> at 13:49 on Wednesday, January 24th, 2007.</span></div></body></html>
|