maruku 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/bin/maruku +74 -22
- data/bin/marutest +15 -3
- data/docs/{changelog-0.3.md → changelog.md} +47 -18
- data/docs/entity_test.html +253 -0
- data/docs/entity_test.md +21 -0
- data/docs/index.html +124 -31
- data/docs/markdown_syntax.html +46 -46
- data/docs/maruku.html +124 -31
- data/docs/maruku.md +47 -9
- data/docs/proposal.html +4 -4
- data/lib/maruku.rb +1 -0
- data/lib/maruku/defaults.rb +1 -1
- data/lib/maruku/helpers.rb +4 -4
- data/lib/maruku/input/parse_block.rb +39 -33
- data/lib/maruku/input/parse_doc.rb +57 -3
- data/lib/maruku/input/parse_span_better.rb +28 -8
- data/lib/maruku/input/rubypants.rb +225 -0
- data/lib/maruku/input/type_detection.rb +1 -0
- data/lib/maruku/output/to_html.rb +46 -47
- data/lib/maruku/output/to_latex.rb +166 -45
- data/lib/maruku/output/to_latex_entities.rb +75 -43
- data/lib/maruku/string_utils.rb +21 -19
- data/lib/maruku/structures.rb +21 -12
- data/lib/maruku/structures_inspect.rb +12 -3
- data/lib/maruku/tests/new_parser.rb +2 -1
- data/lib/maruku/version.rb +1 -1
- data/tests/unittest/abbreviations.md +8 -8
- data/tests/unittest/attributes/attributes.md +10 -10
- data/tests/unittest/attributes/circular.md +4 -4
- data/tests/unittest/attributes/default.md +3 -3
- data/tests/unittest/blank.md +2 -2
- data/tests/unittest/blanks_in_code.md +12 -12
- data/tests/unittest/code.md +4 -4
- data/tests/unittest/code2.md +7 -6
- data/tests/unittest/code3.md +16 -16
- data/tests/unittest/easy.md +4 -4
- data/tests/unittest/email.md +4 -4
- data/tests/unittest/encoding/iso-8859-1.md +2 -2
- data/tests/unittest/encoding/utf-8.md +2 -2
- data/tests/unittest/entities.md +20 -20
- data/tests/unittest/escaping.md +16 -16
- data/tests/unittest/extra_dl.md +17 -7
- data/tests/unittest/extra_header_id.md +11 -11
- data/tests/unittest/extra_table1.md +4 -4
- data/tests/unittest/footnotes.md +38 -28
- data/tests/unittest/headers.md +6 -6
- data/tests/unittest/hrule.md +6 -6
- data/tests/unittest/images.md +18 -16
- data/tests/unittest/inline_html.md +7 -29
- data/tests/unittest/inline_html2.md +3 -3
- data/tests/unittest/links.md +7 -27
- data/tests/unittest/list1.md +9 -8
- data/tests/unittest/list2.md +15 -12
- data/tests/unittest/list3.md +16 -14
- data/tests/unittest/list4.md +4 -4
- data/tests/unittest/lists.md +33 -29
- data/tests/unittest/lists_after_paragraph.md +36 -36
- data/tests/unittest/lists_ol.md +43 -38
- data/tests/unittest/misc_sw.md +172 -156
- data/tests/unittest/notyet/escape.md +8 -8
- data/tests/unittest/notyet/header_after_par.md +6 -6
- data/tests/unittest/notyet/ticks.md +4 -4
- data/tests/unittest/notyet/triggering.md +21 -21
- data/tests/unittest/olist.md +5 -5
- data/tests/unittest/one.md +1 -1
- data/tests/unittest/paragraph.md +1 -1
- data/tests/unittest/paragraph_rules/dont_merge_ref.md +1 -1
- data/tests/unittest/paragraph_rules/tab_is_blank.md +2 -2
- data/tests/unittest/paragraphs.md +5 -5
- data/tests/unittest/recover/recover_links.md +2 -2
- data/tests/unittest/references/long_example.md +27 -19
- data/tests/unittest/smartypants.md +148 -0
- data/tests/unittest/syntax_hl.md +14 -14
- data/tests/unittest/test.md +2 -2
- data/tests/unittest/wrapping.md +8 -8
- data/tests/unittest/xml_instruction.md +82 -0
- metadata +149 -160
- data/docs/TOFIX.html +0 -22
- data/docs/TOFIX.md +0 -3
- data/docs/changelog-0.2.13.html +0 -30
- data/docs/changelog-0.2.13.md +0 -6
- data/docs/changelog-0.3.html +0 -113
- data/docs/faq.html +0 -57
- data/docs/faq.md +0 -32
- data/docs/hidden_o_n_squared.md +0 -10
- data/docs/todo.html +0 -40
- data/docs/todo.md +0 -9
data/docs/entity_test.md
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
|
|
2
|
+
List of symbols supported by Maruku
|
|
3
|
+
===================================
|
|
4
|
+
|
|
5
|
+
<?maruku
|
|
6
|
+
all = []
|
|
7
|
+
ENTITY_TABLE.each do |k, e|
|
|
8
|
+
if k.kind_of? String
|
|
9
|
+
all << (h=md_code("&#{e.html_entity};")) <<
|
|
10
|
+
" " << md_entity(e.html_entity) <<
|
|
11
|
+
" (" << (l=md_code(e.latex_string)) << ") \n" <<
|
|
12
|
+
md_entity('nbsp')<<md_entity('nbsp')<<md_entity('nbsp')
|
|
13
|
+
|
|
14
|
+
h.attributes[:code_background_color] = '#eef'
|
|
15
|
+
l.attributes[:code_background_color] = '#ffe'
|
|
16
|
+
end
|
|
17
|
+
end
|
|
18
|
+
@doc.children.push md_par(all)
|
|
19
|
+
|
|
20
|
+
?>
|
|
21
|
+
|
data/docs/index.html
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
<html lang='en' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'><head><meta content='text/html; charset=utf-8' http-equiv='Content-type' /><title>Maruku: a Markdown-superset interpreter</title><link href='style.css' rel='stylesheet' type='text/css' /></head><body>
|
|
5
5
|
<h1 id='maruku_a_markdownsuperset_interpreter'>Mar<strong>u</strong>k<strong>u</strong>: a Markdown-superset interpreter</h1>
|
|
6
6
|
|
|
7
|
-
<p><a href='http://maruku.rubyforge.org
|
|
7
|
+
<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>
|
|
8
8
|
|
|
9
9
|
<p>Maruku allows you to write in an easy-to-read-and-write syntax, like this:</p>
|
|
10
10
|
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
|
|
43
43
|
<p><strong>Authors</strong>: Maruku has been developed so far by <a href='http://www.dis.uniroma1.it/~acensi/'>Andrea Censi</a>. Contributors are most welcome!</p>
|
|
44
44
|
|
|
45
|
-
<p><strong>The name of the game</strong>: Maruku is the <a href='http://en.wikipedia.org/wiki/Romaji'>romaji</a> translitteration of the <a href='http://en.wikipedia.org/wiki/Katakana'>katakana</a> translitteration of &
|
|
45
|
+
<p><strong>The name of the game</strong>: Maruku is the <a href='http://en.wikipedia.org/wiki/Romaji'>romaji</a> translitteration of the <a href='http://en.wikipedia.org/wiki/Katakana'>katakana</a> translitteration of “Mark”, the first word in Markdown. I chose this name because Ruby is Japanese, and also the sillable “ru” appears in Maruku.</p>
|
|
46
46
|
<hr />
|
|
47
47
|
<p>Table of contents: (<strong>auto-generated by Maruku!</strong>)</p>
|
|
48
48
|
<div class='maruku_toc'><ul style='list-style: none;'><li><span class='maruku_section_number'>1. </span><a href='#release_notes'>Release notes</a></li><li><span class='maruku_section_number'>2. </span><a href='#download'>Download</a><ul style='list-style: none;'><li><span class='maruku_section_number'>2.1. </span><a href='#bugs_report'>Bugs report</a></li></ul></li><li><span class='maruku_section_number'>3. </span><a href='#usage'>Usage</a><ul style='list-style: none;'><li><span class='maruku_section_number'>3.1. </span><a href='#from_the_command_line'>From the command line</a></li></ul></li><li><span class='maruku_section_number'>4. </span><a href='#extra'>Examples of PHP Markdown Extra syntax</a></li><li><span class='maruku_section_number'>5. </span><a href='#maruku-and-bluecloth'>Maruku and Bluecloth</a></li><li><span class='maruku_section_number'>6. </span><a href='#meta'>New meta-data syntax</a><ul style='list-style: none;'><li><span class='maruku_section_number'>6.1. </span><a href='#metadata_for_blocklevel_and_spanlevel_elements'>Meta-data for block-level and span-level elements</a></li><li><span class='maruku_section_number'>6.2. </span><a href='#metadata_for_the_document'>Meta-data for the document</a></li><li><span class='maruku_section_number'>6.3. </span><a href='#metalist'>List of meta-data</a></li><li><span class='maruku_section_number'>6.4. </span><a href='#examples'>Examples</a></li></ul></li><li><span class='maruku_section_number'>7. </span><a href='#features'>Other Features</a><ul style='list-style: none;'><li><span class='maruku_section_number'>7.1. </span><a href='#automatic_generation_of_the_table_of_contents'>Automatic generation of the table of contents</a></li><li><span class='maruku_section_number'>7.2. </span><a href='#this_header_contains_emphasis_strong_text_and_'>This header contains <em>emphasis</em> <strong>strong text</strong> and <code>code</code></a></li><li><span class='maruku_section_number'>7.3. </span><a href='#use_html_entities'>Use HTML entities</a></li></ul></li><li><span class='maruku_section_number'>8. </span><a href='#future'>Future developments</a><ul style='list-style: none;'><li><span class='maruku_section_number'>8.1. </span><a href='#a_syntax_for_adding_math'>A syntax for adding math</a></li></ul></li></ul></div><hr />
|
|
@@ -54,6 +54,54 @@
|
|
|
54
54
|
|
|
55
55
|
<p>Have fun!</p>
|
|
56
56
|
|
|
57
|
+
<h4 id='changes_in_041_aka_typographer'>Changes in 0.4.1 aka “Typographer”</h4>
|
|
58
|
+
|
|
59
|
+
<ul>
|
|
60
|
+
<li>
|
|
61
|
+
<p>Implemented SmartyPants support:</p>
|
|
62
|
+
<pre><code>'Twas a "test" to 'remember' -- in the '90s
|
|
63
|
+
--- while I was <<ok>>. She was 6\"12\'.</code></pre>
|
|
64
|
+
<blockquote>
|
|
65
|
+
<p>‘Twas a “test” to ‘remember’ – in the ’90s — while I was «ok». She was 6"12'.</p>
|
|
66
|
+
</blockquote>
|
|
67
|
+
|
|
68
|
+
<p>I adapted the code from RubyPants.</p>
|
|
69
|
+
</li>
|
|
70
|
+
|
|
71
|
+
<li>
|
|
72
|
+
<p>Server directives between <code><? ?></code> are properly preserved.</p>
|
|
73
|
+
</li>
|
|
74
|
+
|
|
75
|
+
<li>
|
|
76
|
+
<p>Changes in LaTeX export:</p>
|
|
77
|
+
|
|
78
|
+
<ul>
|
|
79
|
+
<li>
|
|
80
|
+
<p>Now Japanese text rendering sort of works, using the following packages:</p>
|
|
81
|
+
<pre><code>\usepackage[C40]{fontenc}
|
|
82
|
+
\usepackage[cjkjis]{ucs}
|
|
83
|
+
\usepackage[utf8x]{inputenc}
|
|
84
|
+
</code></pre>
|
|
85
|
+
<p>Nevertheless, I could only get bitmap fonts working – probably it’s a problem with my setup.</p>
|
|
86
|
+
|
|
87
|
+
<p>A quick test: 日本、中国、ひらがな、カタカナ。</p>
|
|
88
|
+
</li>
|
|
89
|
+
|
|
90
|
+
<li>
|
|
91
|
+
<p>Fixed bugs in rendering of immediate links.</p>
|
|
92
|
+
</li>
|
|
93
|
+
|
|
94
|
+
<li>
|
|
95
|
+
<p>External packages are <code>require</code>d only if needed.</p>
|
|
96
|
+
</li>
|
|
97
|
+
|
|
98
|
+
<li>
|
|
99
|
+
<p>More symbols supported. See the symbol list <a href='http://maruku.rubyforge.org/entity_test.html'>in HTML</a> and <a href='http://maruku.rubyforge.org/entity_test.pdf'>in PDF</a>.</p>
|
|
100
|
+
</li>
|
|
101
|
+
</ul>
|
|
102
|
+
</li>
|
|
103
|
+
</ul>
|
|
104
|
+
|
|
57
105
|
<h4 id='changes_in_04'>Changes in 0.4</h4>
|
|
58
106
|
|
|
59
107
|
<ul>
|
|
@@ -63,7 +111,7 @@
|
|
|
63
111
|
|
|
64
112
|
<li>Created <a href='http://maruku.rubyforge.org/rdoc/'>the RDOC documentation</a>.</li>
|
|
65
113
|
|
|
66
|
-
<li>The <code>add_whitespace</code> method took too much time
|
|
114
|
+
<li>The <code>add_whitespace</code> method took too much time – it was O(n^2).</li>
|
|
67
115
|
|
|
68
116
|
<li>Added unit-tests for block-level elements.</li>
|
|
69
117
|
</ul>
|
|
@@ -125,7 +173,7 @@ Maruku (to_latex): parsing 0.49 sec + rendering 0.25 sec = 0.73 sec</code></pr
|
|
|
125
173
|
<p>(日本のガルは 大好き、でも、日本語は難しですから、そうぞ 英語話すガルを おしえてください).</p>
|
|
126
174
|
</blockquote>
|
|
127
175
|
|
|
128
|
-
<p>In the LaTeX version, these do not appear. I know how to do LaTeX with ISO-8859-1 encoding (European characters), but I&
|
|
176
|
+
<p>In the LaTeX version, these do not appear. I know how to do LaTeX with ISO-8859-1 encoding (European characters), but I’m struggling with half-baked solutions for UTF-8 encoded documents.</p>
|
|
129
177
|
</li>
|
|
130
178
|
|
|
131
179
|
<li>
|
|
@@ -154,11 +202,11 @@ Maruku (to_latex): parsing 0.49 sec + rendering 0.25 sec = 0.73 sec</code></pr
|
|
|
154
202
|
<p>The development site is <a href='http://rubyforge.org/projects/maruku/'>http://rubyforge.org/projects/maruku/</a>.</p>
|
|
155
203
|
|
|
156
204
|
<p>Install with:</p>
|
|
157
|
-
<pre class='
|
|
205
|
+
<pre class='sh' style='background-color: #efefff;'>$ gem install maruku</pre>
|
|
158
206
|
<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>
|
|
159
207
|
|
|
160
208
|
<p>Anonymous access to the repository is possible with:</p>
|
|
161
|
-
<pre class='
|
|
209
|
+
<pre class='sh' style='background-color: #efefff;'>$ svn checkout svn://rubyforge.org/var/svn/maruku</pre>
|
|
162
210
|
<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>
|
|
163
211
|
|
|
164
212
|
<h3 id='bugs_report'><span class='maruku_section_number'>2.1. </span>Bugs report</h3>
|
|
@@ -184,11 +232,11 @@ Maruku (to_latex): parsing 0.49 sec + rendering 0.25 sec = 0.73 sec</code></pr
|
|
|
184
232
|
<ul>
|
|
185
233
|
<li>
|
|
186
234
|
<p><code>maruku</code> converts Markdown to HTML:</p>
|
|
187
|
-
<pre class='
|
|
235
|
+
<pre class='sh' style='background-color: #efefff;'>$ maruku file.md # creates file.html</pre></li>
|
|
188
236
|
|
|
189
237
|
<li>
|
|
190
238
|
<p><code>marutex</code> converts Markdown to LaTeX, then calls <code>pdflatex</code> to transform to PDF:</p>
|
|
191
|
-
<pre class='
|
|
239
|
+
<pre class='sh' style='background-color: #efefff;'>$ marutex file.md # creates file.tex and file.pdf</pre></li>
|
|
192
240
|
</ul>
|
|
193
241
|
|
|
194
242
|
<h2 id='extra'><span class='maruku_section_number'>4. </span>Examples of PHP Markdown Extra syntax</h2>
|
|
@@ -196,15 +244,15 @@ Maruku (to_latex): parsing 0.49 sec + rendering 0.25 sec = 0.73 sec</code></pr
|
|
|
196
244
|
<ul>
|
|
197
245
|
<li>
|
|
198
246
|
<p>tables</p>
|
|
199
|
-
<pre
|
|
247
|
+
<pre style='background-color: #ffefef;'><code>Col1 | Very very long head | Very very long head|
|
|
200
248
|
-----|:-------------------:|-------------------:|
|
|
201
|
-
cell | center-align | right-align |</pre><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></tr></tbody></table></li>
|
|
249
|
+
cell | center-align | right-align |</code></pre><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></tr></tbody></table></li>
|
|
202
250
|
|
|
203
251
|
<li>
|
|
204
252
|
<p>footnotes <sup id='fnref:1'><a href='#fn:1' rel='footnote'>1</a></sup></p>
|
|
205
|
-
<pre
|
|
253
|
+
<pre style='background-color: #ffefef;'><code>* footnotes [^foot]
|
|
206
254
|
|
|
207
|
-
[^foot]: I really was missing those.</pre></li>
|
|
255
|
+
[^foot]: I really was missing those.</code></pre></li>
|
|
208
256
|
</ul>
|
|
209
257
|
|
|
210
258
|
<ul>
|
|
@@ -218,14 +266,20 @@ cell | center-align | right-align |</pre><table><thead><tr><th>Col
|
|
|
218
266
|
|
|
219
267
|
<li>
|
|
220
268
|
<p>header ids</p>
|
|
221
|
-
<pre
|
|
269
|
+
<pre style='background-color: #ffefef;'><code>## Download ## {#download}</code></pre>
|
|
222
270
|
<p>For example, <a href='#download'>a link to the download</a> header.</p>
|
|
223
271
|
</li>
|
|
224
272
|
|
|
225
273
|
<li>
|
|
226
274
|
<p>definition lists</p>
|
|
227
|
-
<pre
|
|
228
|
-
: something very hard to parse</pre
|
|
275
|
+
<pre style='background-color: #ffefef;'><code>Definition list
|
|
276
|
+
: something very hard to parse</code></pre>
|
|
277
|
+
<dl>
|
|
278
|
+
<dt>Definition list</dt>
|
|
279
|
+
|
|
280
|
+
<dd>something very hard to parse</dd>
|
|
281
|
+
</dl>
|
|
282
|
+
</li>
|
|
229
283
|
|
|
230
284
|
<li>
|
|
231
285
|
<p>abbreviations or <abbr title='Simply an abbreviation'>ABB</abbr> for short.</p>
|
|
@@ -254,7 +308,7 @@ cell | center-align | right-align |</pre><table><thead><tr><th>Col
|
|
|
254
308
|
|
|
255
309
|
<h2 id='meta'><span class='maruku_section_number'>6. </span>New meta-data syntax</h2>
|
|
256
310
|
|
|
257
|
-
<p>Maruku implements a syntax that allows to attach &
|
|
311
|
+
<p>Maruku implements a syntax that allows to attach “meta” information to objects.</p>
|
|
258
312
|
|
|
259
313
|
<h3 id='metadata_for_blocklevel_and_spanlevel_elements'><span class='maruku_section_number'>6.1. </span>Meta-data for block-level and span-level elements</h3>
|
|
260
314
|
|
|
@@ -263,10 +317,11 @@ cell | center-align | right-align |</pre><table><thead><tr><th>Col
|
|
|
263
317
|
<h3 id='metadata_for_the_document'><span class='maruku_section_number'>6.2. </span>Meta-data for the document</h3>
|
|
264
318
|
|
|
265
319
|
<p>Meta-data for the document itself is specified through the use of email headers:</p>
|
|
266
|
-
<pre
|
|
320
|
+
<pre style='background-color: #ffefef;'><code>Title: A simple document containing meta-headers
|
|
267
321
|
CSS: style.css
|
|
268
322
|
|
|
269
|
-
Content of the document
|
|
323
|
+
Content of the document
|
|
324
|
+
</code></pre>
|
|
270
325
|
<p>When creating the document through</p>
|
|
271
326
|
<pre class='ruby' style='background-color: #efffef;'><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></pre>
|
|
272
327
|
<p>the title and stylesheet are added as expected.</p>
|
|
@@ -274,29 +329,65 @@ Content of the document</pre>
|
|
|
274
329
|
<p>Meta-data keys are assumed to be case-insensitive.</p>
|
|
275
330
|
<hr />
|
|
276
331
|
<h3 id='metalist'><span class='maruku_section_number'>6.3. </span>List of meta-data</h3>
|
|
277
|
-
|
|
332
|
+
|
|
333
|
+
<dl>
|
|
334
|
+
<dt><strong><code>title</code>, <code>subject</code></strong></dt>
|
|
335
|
+
|
|
336
|
+
<dd>
|
|
278
337
|
<p>(document) Sets the title of the document (HTML: used in the <code>TITLE</code> element).</p>
|
|
279
|
-
</dd
|
|
338
|
+
</dd>
|
|
339
|
+
|
|
340
|
+
<dt><strong><code>use_numbered_headers</code></strong></dt>
|
|
341
|
+
|
|
342
|
+
<dd>
|
|
280
343
|
<p>(document) If <code>true</code>, headers are numbered (just like this document). Default is <code>false</code>.</p>
|
|
281
|
-
</dd
|
|
344
|
+
</dd>
|
|
345
|
+
|
|
346
|
+
<dt><strong><code>css</code></strong></dt>
|
|
347
|
+
|
|
348
|
+
<dd>
|
|
282
349
|
<p>(document, HTML) Url of stylesheet.</p>
|
|
283
|
-
</dd
|
|
350
|
+
</dd>
|
|
351
|
+
|
|
352
|
+
<dt><strong><code>html_use_syntax</code></strong></dt>
|
|
353
|
+
|
|
354
|
+
<dd>
|
|
284
355
|
<p>(document, HTML) If set, use the <a href='http://syntax.rubyforge.org/'>Ruby <code>syntax</code> library</a> to add source highlighting.</p>
|
|
285
|
-
</dd
|
|
356
|
+
</dd>
|
|
357
|
+
|
|
358
|
+
<dt><strong><code>latex_use_listings</code></strong></dt>
|
|
359
|
+
|
|
360
|
+
<dd>
|
|
286
361
|
<p>(document, LaTeX) If set, use the fancy <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><code>listings</code> package</a> for better displaying code blocks.</p>
|
|
287
362
|
|
|
288
363
|
<p>If not set, use standard <code>verbatim</code> environment.</p>
|
|
289
|
-
</dd
|
|
364
|
+
</dd>
|
|
365
|
+
|
|
366
|
+
<dt><strong><code>style</code>, <code>id</code>, <code>class</code></strong></dt>
|
|
367
|
+
|
|
368
|
+
<dd>
|
|
290
369
|
<p>(any block object, HTML) Standard CSS attributes are copied.</p>
|
|
291
|
-
</dd
|
|
370
|
+
</dd>
|
|
371
|
+
|
|
372
|
+
<dt><strong><code>lang</code></strong></dt>
|
|
373
|
+
|
|
374
|
+
<dd>
|
|
292
375
|
<p>(code blocks) Name of programming language (<code>ruby</code>) for syntax highlighting.</p>
|
|
293
376
|
|
|
294
377
|
<p>Default for this is <code>code_lang</code> in document.</p>
|
|
295
378
|
|
|
296
379
|
<p>Syntax highlighting is delegated to the <a href='http://syntax.rubyforge.org/'><code>syntax</code> library</a> for HTML output and to the <a href='http://www.ctan.org/tex-archive/macros/latex/contrib/listings/'><code>listings</code> package</a> for LaTeX output.</p>
|
|
297
|
-
</dd
|
|
380
|
+
</dd>
|
|
381
|
+
|
|
382
|
+
<dt><strong><code>code_show_spaces</code></strong></dt>
|
|
383
|
+
|
|
384
|
+
<dd>
|
|
298
385
|
<p>Shows tabs and newlines (default is read in the document object).</p>
|
|
299
|
-
</dd
|
|
386
|
+
</dd>
|
|
387
|
+
|
|
388
|
+
<dt><strong><code>code_background_color</code></strong></dt>
|
|
389
|
+
|
|
390
|
+
<dd>
|
|
300
391
|
<p>Background color for code blocks. (default is read in the document object).</p>
|
|
301
392
|
|
|
302
393
|
<p>The format is either a named color (<code>green</code>, <code>red</code>) or a CSS color of the form <code>#ff00ff</code>.</p>
|
|
@@ -312,15 +403,17 @@ Content of the document</pre>
|
|
|
312
403
|
<p>For example, for <code>#0000ff</code>, the macro is called as: <code>\color[rgb]{0,0,1}</code>.</p>
|
|
313
404
|
</li>
|
|
314
405
|
</ul>
|
|
315
|
-
</dd
|
|
406
|
+
</dd>
|
|
407
|
+
</dl>
|
|
408
|
+
|
|
316
409
|
<h3 id='examples'><span class='maruku_section_number'>6.4. </span>Examples</h3>
|
|
317
410
|
|
|
318
411
|
<p>An example of this is the following:</p>
|
|
319
|
-
<pre
|
|
412
|
+
<pre style='background-color: #ffefef;'><code> One space
|
|
320
413
|
Two spaces
|
|
321
414
|
Tab, space, tab
|
|
322
415
|
Tab, tab, tab and all is green!
|
|
323
|
-
{code_show_spaces code_background_color=#ffeedd}</pre>
|
|
416
|
+
{code_show_spaces code_background_color=#ffeedd}</code></pre>
|
|
324
417
|
<p>That will produce:</p>
|
|
325
418
|
<pre style='background-color: #ffeedd;'><code>¬One¬space
|
|
326
419
|
¬¬Two¬spaces
|
|
@@ -368,4 +461,4 @@ $ \alpha = \beta + \gamma $ (eq:1)
|
|
|
368
461
|
|
|
369
462
|
This is a reference to equation: please see (eq:1)</code></pre><div class='footnotes'><hr /><ol><li id='fn:1'>
|
|
370
463
|
<p>I really was missing those.</p>
|
|
371
|
-
<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 interpreter'>Maruku</a> at
|
|
464
|
+
<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 interpreter for Ruby'>Maruku</a> at 23:43 on Monday, January 08th, 2007.</span></div></body></html>
|
data/docs/markdown_syntax.html
CHANGED
|
@@ -66,21 +66,21 @@
|
|
|
66
66
|
</li>
|
|
67
67
|
</ul>
|
|
68
68
|
|
|
69
|
-
<p><strong>Note:</strong> This document is itself written using Markdown; you can <a href='/projects/markdown/syntax.text'>see the source for it by adding &
|
|
69
|
+
<p><strong>Note:</strong> This document is itself written using Markdown; you can <a href='/projects/markdown/syntax.text'>see the source for it by adding ‘.text’ to the URL</a>.</p>
|
|
70
70
|
<hr /><h2 id='overview'>Overview</h2><h3 id='philosophy'>Philosophy</h3>
|
|
71
71
|
<p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.</p>
|
|
72
72
|
|
|
73
|
-
<p>Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it&
|
|
73
|
+
<p>Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML 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>, <a href='http://www.triptico.com/software/grutatxt.html'>Grutatext</a>, and <a href='http://ettext.taint.org/doc/'>EtText</a> – the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.</p>
|
|
74
74
|
|
|
75
|
-
<p>To this end, Markdown&
|
|
75
|
+
<p>To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.</p>
|
|
76
76
|
<h3 id='html'>Inline HTML</h3>
|
|
77
|
-
<p>Markdown&
|
|
77
|
+
<p>Markdown’s syntax is intended for one purpose: to be used as a format for <em>writing</em> for the web.</p>
|
|
78
78
|
|
|
79
|
-
<p>Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is <em>not</em> to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a <em>publishing</em> format; Markdown is a <em>writing</em> format. Thus, Markdown&
|
|
79
|
+
<p>Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is <em>not</em> to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a <em>publishing</em> format; Markdown is a <em>writing</em> format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.</p>
|
|
80
80
|
|
|
81
|
-
<p>For any markup that is not covered by Markdown&
|
|
81
|
+
<p>For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.</p>
|
|
82
82
|
|
|
83
|
-
<p>The only restrictions are that block-level HTML elements
|
|
83
|
+
<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>
|
|
84
84
|
|
|
85
85
|
<p>For example, to add an HTML table to a Markdown article:</p>
|
|
86
86
|
<pre><code>This is a regular paragraph.
|
|
@@ -93,15 +93,15 @@
|
|
|
93
93
|
|
|
94
94
|
This is another regular paragraph.
|
|
95
95
|
</code></pre>
|
|
96
|
-
<p>Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can&
|
|
96
|
+
<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>
|
|
97
97
|
|
|
98
|
-
<p>Span-level HTML tags
|
|
98
|
+
<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>
|
|
99
99
|
|
|
100
100
|
<p>Unlike block-level HTML tags, Markdown syntax <em>is</em> processed within span-level tags.</p>
|
|
101
101
|
<h3 id='autoescape'>Automatic Escaping for Special Characters</h3>
|
|
102
102
|
<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>
|
|
103
103
|
|
|
104
|
-
<p>Ampersands in particular are bedeviling for web writers. If you want to write about &
|
|
104
|
+
<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>
|
|
105
105
|
<pre><code>http://images.google.com/images?num=30&q=larry+bird
|
|
106
106
|
</code></pre>
|
|
107
107
|
<p>you need to encode the URL as:</p>
|
|
@@ -128,24 +128,24 @@ This is another regular paragraph.
|
|
|
128
128
|
</code></pre>
|
|
129
129
|
<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>
|
|
130
130
|
<hr /><h2 id='block'>Block Elements</h2><h3 id='p'>Paragraphs and Line Breaks</h3>
|
|
131
|
-
<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
|
|
131
|
+
<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>
|
|
132
132
|
|
|
133
|
-
<p>The implication of the &
|
|
133
|
+
<p>The implication of the “one or more consecutive lines of text” rule is that Markdown supports “hard-wrapped” text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s “Convert Line Breaks” option) which translate every line break character in a paragraph into a <code><br /></code> tag.</p>
|
|
134
134
|
|
|
135
135
|
<p>When you <em>do</em> want to insert a <code><br /></code> break tag using Markdown, you end a line with two or more spaces, then type return.</p>
|
|
136
136
|
|
|
137
|
-
<p>Yes, this takes a tad more effort to create a <code><br /></code>, but a simplistic &
|
|
137
|
+
<p>Yes, this takes a tad more effort to create a <code><br /></code>, but a simplistic “every line break is a <code><br /></code>” rule wouldn’t work for Markdown. Markdown’s email-style <a href='#blockquote'>blockquoting</a> and multi-paragraph <a href='#list'>list items</a> work best – and look better – when you format them with hard breaks.</p>
|
|
138
138
|
<h3 id='header'>Headers</h3>
|
|
139
139
|
<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>
|
|
140
140
|
|
|
141
|
-
<p>Setext-style headers are &
|
|
141
|
+
<p>Setext-style headers are “underlined” using equal signs (for first-level headers) and dashes (for second-level headers). For example:</p>
|
|
142
142
|
<pre><code>This is an H1
|
|
143
143
|
=============
|
|
144
144
|
|
|
145
145
|
This is an H2
|
|
146
146
|
-------------
|
|
147
147
|
</code></pre>
|
|
148
|
-
<p>Any number of underlining <code>=</code>&
|
|
148
|
+
<p>Any number of underlining <code>=</code>’s or <code>-</code>’s will work.</p>
|
|
149
149
|
|
|
150
150
|
<p>Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example:</p>
|
|
151
151
|
<pre><code># This is an H1
|
|
@@ -154,7 +154,7 @@ This is an H2
|
|
|
154
154
|
|
|
155
155
|
###### This is an H6
|
|
156
156
|
</code></pre>
|
|
157
|
-
<p>Optionally, you may &
|
|
157
|
+
<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>
|
|
158
158
|
<pre><code># This is an H1 #
|
|
159
159
|
|
|
160
160
|
## This is an H2 ##
|
|
@@ -162,7 +162,7 @@ This is an H2
|
|
|
162
162
|
### This is an H3 ######
|
|
163
163
|
|
|
164
164
|
</code></pre><h3 id='blockquote'>Blockquotes</h3>
|
|
165
|
-
<p>Markdown uses email-style <code>></code> characters for blockquoting. If you&
|
|
165
|
+
<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>
|
|
166
166
|
<pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
|
167
167
|
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
|
168
168
|
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
|
@@ -199,7 +199,7 @@ id sem consectetuer libero luctus adipiscing.
|
|
|
199
199
|
<h3 id='list'>Lists</h3>
|
|
200
200
|
<p>Markdown supports ordered (numbered) and unordered (bulleted) lists.</p>
|
|
201
201
|
|
|
202
|
-
<p>Unordered lists use asterisks, pluses, and hyphens
|
|
202
|
+
<p>Unordered lists use asterisks, pluses, and hyphens – interchangably – as list markers:</p>
|
|
203
203
|
<pre><code>* Red
|
|
204
204
|
* Green
|
|
205
205
|
* Blue
|
|
@@ -219,7 +219,7 @@ id sem consectetuer libero luctus adipiscing.
|
|
|
219
219
|
2. McHale
|
|
220
220
|
3. Parish
|
|
221
221
|
</code></pre>
|
|
222
|
-
<p>It&
|
|
222
|
+
<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>
|
|
223
223
|
<pre><code><ol>
|
|
224
224
|
<li>Bird</li>
|
|
225
225
|
<li>McHale</li>
|
|
@@ -236,7 +236,7 @@ id sem consectetuer libero luctus adipiscing.
|
|
|
236
236
|
1. McHale
|
|
237
237
|
8. Parish
|
|
238
238
|
</code></pre>
|
|
239
|
-
<p>you&
|
|
239
|
+
<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>
|
|
240
240
|
|
|
241
241
|
<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>
|
|
242
242
|
|
|
@@ -249,7 +249,7 @@ id sem consectetuer libero luctus adipiscing.
|
|
|
249
249
|
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
|
250
250
|
Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
251
251
|
</code></pre>
|
|
252
|
-
<p>But if you want to be lazy, you don&
|
|
252
|
+
<p>But if you want to be lazy, you don’t have to:</p>
|
|
253
253
|
<pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
254
254
|
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
|
255
255
|
viverra nec, fringilla in, laoreet vitae, risus.
|
|
@@ -297,19 +297,19 @@ sit amet, consectetuer adipiscing elit.
|
|
|
297
297
|
|
|
298
298
|
* Another item in the same list.
|
|
299
299
|
</code></pre>
|
|
300
|
-
<p>To put a blockquote within a list item, the blockquote&
|
|
300
|
+
<p>To put a blockquote within a list item, the blockquote’s <code>></code> delimiters need to be indented:</p>
|
|
301
301
|
<pre><code>* A list item with a blockquote:
|
|
302
302
|
|
|
303
303
|
> This is a blockquote
|
|
304
304
|
> inside a list item.
|
|
305
305
|
</code></pre>
|
|
306
|
-
<p>To put a code block within a list item, the code block needs to be indented <em>twice</em>
|
|
306
|
+
<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>
|
|
307
307
|
<pre><code>* A list item with a code block:
|
|
308
308
|
|
|
309
309
|
<code goes here>
|
|
310
310
|
|
|
311
311
|
</code></pre>
|
|
312
|
-
<p>It&
|
|
312
|
+
<p>It’s worth noting that it’s possible to trigger an ordered list by accident, by writing something like this:</p>
|
|
313
313
|
<pre><code>1986. What a great season.
|
|
314
314
|
</code></pre>
|
|
315
315
|
<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>
|
|
@@ -330,7 +330,7 @@ sit amet, consectetuer adipiscing elit.
|
|
|
330
330
|
<pre><code>This is a code block.
|
|
331
331
|
</code></pre>
|
|
332
332
|
</code></pre>
|
|
333
|
-
<p>One level of indentation
|
|
333
|
+
<p>One level of indentation – 4 spaces or 1 tab – is removed from each line of the code block. For example, this:</p>
|
|
334
334
|
<pre><code>Here is an example of AppleScript:
|
|
335
335
|
|
|
336
336
|
tell application "Foo"
|
|
@@ -347,7 +347,7 @@ end tell
|
|
|
347
347
|
</code></pre>
|
|
348
348
|
<p>A code block continues until it reaches a line that is not indented (or the end of the article).</p>
|
|
349
349
|
|
|
350
|
-
<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
|
|
350
|
+
<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>
|
|
351
351
|
<pre><code> <div class="footer">
|
|
352
352
|
&copy; 2004 Foo Corporation
|
|
353
353
|
</div>
|
|
@@ -358,7 +358,7 @@ end tell
|
|
|
358
358
|
&lt;/div&gt;
|
|
359
359
|
</code></pre>
|
|
360
360
|
</code></pre>
|
|
361
|
-
<p>Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it&
|
|
361
|
+
<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>
|
|
362
362
|
<h3 id='hr'>Horizontal Rules</h3>
|
|
363
363
|
<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>
|
|
364
364
|
<pre><code>* * *
|
|
@@ -376,7 +376,7 @@ end tell
|
|
|
376
376
|
|
|
377
377
|
<p>In both styles, the link text is delimited by square brackets.</p>
|
|
378
378
|
|
|
379
|
-
<p>To create an inline link, use a set of regular parentheses immediately after the link text&
|
|
379
|
+
<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>
|
|
380
380
|
<pre><code>This is [an example](http://example.com/ "Title") inline link.
|
|
381
381
|
|
|
382
382
|
[This link](http://example.net/) has no title attribute.
|
|
@@ -388,7 +388,7 @@ an example</a> inline link.</p>
|
|
|
388
388
|
<p><a href="http://example.net/">This link</a> has no
|
|
389
389
|
title attribute.</p>
|
|
390
390
|
</code></pre>
|
|
391
|
-
<p>If you&
|
|
391
|
+
<p>If you’re referring to a local resource on the same server, you can use relative paths:</p>
|
|
392
392
|
<pre><code>See my [About](/about/) page for details.
|
|
393
393
|
</code></pre>
|
|
394
394
|
<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>
|
|
@@ -430,13 +430,13 @@ title attribute.</p>
|
|
|
430
430
|
</code></pre>
|
|
431
431
|
<p>Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.</p>
|
|
432
432
|
|
|
433
|
-
<p>Link definition names may constist of letters, numbers, spaces, and punctuation
|
|
433
|
+
<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>
|
|
434
434
|
<pre><code>[link text][a]
|
|
435
435
|
[link text][A]
|
|
436
436
|
</code></pre>
|
|
437
437
|
<p>are equivalent.</p>
|
|
438
438
|
|
|
439
|
-
<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
|
|
439
|
+
<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>
|
|
440
440
|
<pre><code>[Google][]
|
|
441
441
|
</code></pre>
|
|
442
442
|
<p>And then define the link:</p>
|
|
@@ -448,9 +448,9 @@ title attribute.</p>
|
|
|
448
448
|
<p>And then define the link:</p>
|
|
449
449
|
<pre><code>[Daring Fireball]: http://daringfireball.net/
|
|
450
450
|
</code></pre>
|
|
451
|
-
<p>Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they&
|
|
451
|
+
<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>
|
|
452
452
|
|
|
453
|
-
<p>Here&
|
|
453
|
+
<p>Here’s an example of reference links in action:</p>
|
|
454
454
|
<pre><code>I get 10 times more traffic from [Google] [1] than from
|
|
455
455
|
[Yahoo] [2] or [MSN] [3].
|
|
456
456
|
|
|
@@ -472,16 +472,16 @@ title="Google">Google</a> than from
|
|
|
472
472
|
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
|
|
473
473
|
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
|
|
474
474
|
</code></pre>
|
|
475
|
-
<p>For comparison, here is the same paragraph written using Markdown&
|
|
475
|
+
<p>For comparison, here is the same paragraph written using Markdown’s inline link style:</p>
|
|
476
476
|
<pre><code>I get 10 times more traffic from [Google](http://google.com/ "Google")
|
|
477
477
|
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
|
|
478
478
|
[MSN](http://search.msn.com/ "MSN Search").
|
|
479
479
|
</code></pre>
|
|
480
|
-
<p>The point of reference-style links is not that they&
|
|
480
|
+
<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>
|
|
481
481
|
|
|
482
|
-
<p>With Markdown&
|
|
482
|
+
<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>
|
|
483
483
|
<h3 id='em'>Emphasis</h3>
|
|
484
|
-
<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>&
|
|
484
|
+
<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>
|
|
485
485
|
<pre><code>*single asterisks*
|
|
486
486
|
|
|
487
487
|
_single underscores_
|
|
@@ -504,7 +504,7 @@ __double underscores__
|
|
|
504
504
|
<p>Emphasis can be used in the middle of a word:</p>
|
|
505
505
|
<pre><code>un*fucking*believable
|
|
506
506
|
</code></pre>
|
|
507
|
-
<p>But if you surround an <code>*</code> or <code>_</code> with spaces, it&
|
|
507
|
+
<p>But if you surround an <code>*</code> or <code>_</code> with spaces, it’ll be treated as a literal asterisk or underscore.</p>
|
|
508
508
|
|
|
509
509
|
<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>
|
|
510
510
|
<pre><code>\*this text is surrounded by literal asterisks\*
|
|
@@ -523,7 +523,7 @@ __double underscores__
|
|
|
523
523
|
<p>which will produce this:</p>
|
|
524
524
|
<pre><code><p><code>There is a literal backtick (`) here.</code></p>
|
|
525
525
|
</code></pre>
|
|
526
|
-
<p>The backtick delimiters surrounding a code span may include spaces
|
|
526
|
+
<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>
|
|
527
527
|
<pre><code>A single backtick in a code span: `` ` ``
|
|
528
528
|
|
|
529
529
|
A backtick-delimited string in a code span: `` `foo` ``
|
|
@@ -548,7 +548,7 @@ equivalent of <code>&amp;mdash;</code>.</p>
|
|
|
548
548
|
|
|
549
549
|
|
|
550
550
|
</code></pre><h3 id='img'>Images</h3>
|
|
551
|
-
<p>Admittedly, it&
|
|
551
|
+
<p>Admittedly, it’s fairly difficult to devise a “natural” syntax for placing images into a plain text document format.</p>
|
|
552
552
|
|
|
553
553
|
<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>
|
|
554
554
|
|
|
@@ -570,12 +570,12 @@ equivalent of <code>&amp;mdash;</code>.</p>
|
|
|
570
570
|
<p>Reference-style image syntax looks like this:</p>
|
|
571
571
|
<pre><code>![Alt text][id]
|
|
572
572
|
</code></pre>
|
|
573
|
-
<p>Where &
|
|
573
|
+
<p>Where “id” is the name of a defined image reference. Image references are defined using syntax identical to link references:</p>
|
|
574
574
|
<pre><code>[id]: url/to/image "Optional title attribute"
|
|
575
575
|
</code></pre>
|
|
576
576
|
<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>
|
|
577
577
|
<hr /><h2 id='misc'>Miscellaneous</h2><h3 id='autolink'>Automatic Links</h3>
|
|
578
|
-
<p>Markdown supports a shortcut style for creating &
|
|
578
|
+
<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>
|
|
579
579
|
<pre><code><http://example.com/></code></pre>
|
|
580
580
|
<p>Markdown will turn this into:</p>
|
|
581
581
|
<pre><code><a href="http://example.com/">http://example.com/</a>
|
|
@@ -589,11 +589,11 @@ equivalent of <code>&amp;mdash;</code>.</p>
|
|
|
589
589
|
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
|
|
590
590
|
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
|
|
591
591
|
</code></pre>
|
|
592
|
-
<p>which will render in a browser as a clickable link to &
|
|
592
|
+
<p>which will render in a browser as a clickable link to “address@example.com”.</p>
|
|
593
593
|
|
|
594
|
-
<p>(This sort of entity-encoding trick will indeed fool many, if not most, address-harvesting bots, but it definitely won&
|
|
594
|
+
<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>
|
|
595
595
|
<h3 id='backslash'>Backslash Escapes</h3>
|
|
596
|
-
<p>Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown&
|
|
596
|
+
<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>
|
|
597
597
|
<pre><code>\*literal asterisks\*
|
|
598
598
|
</code></pre>
|
|
599
599
|
<p>Markdown provides backslash escapes for the following characters:</p>
|
|
@@ -608,4 +608,4 @@ _ underscore
|
|
|
608
608
|
+ plus sign
|
|
609
609
|
- minus sign (hyphen)
|
|
610
610
|
. dot
|
|
611
|
-
! exclamation mark</code></pre><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 interpreter'>Maruku</a> at
|
|
611
|
+
! exclamation mark</code></pre><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 interpreter for Ruby'>Maruku</a> at 23:18 on Monday, January 08th, 2007.</span></div></body></html>
|