maruku 0.3.0 → 0.4.0
Sign up to get free protection for your applications and to get access to all the features.
- data/bin/{maruku0.3 → marudown} +6 -14
- data/bin/maruku +1 -1
- data/bin/marutest +37 -9
- data/docs/TOFIX.html +22 -0
- data/docs/TOFIX.md +3 -0
- data/docs/changelog-0.2.13.html +30 -0
- data/docs/changelog-0.2.13.md +6 -0
- data/docs/changelog-0.3.html +19 -5
- data/docs/faq.html +51 -40
- data/docs/faq.md +3 -3
- data/docs/hidden_o_n_squared.md +10 -0
- data/docs/index.html +84 -396
- data/docs/markdown_syntax.html +139 -330
- data/docs/markdown_syntax.md +80 -93
- data/docs/maruku.html +84 -396
- data/docs/maruku.md +88 -158
- data/docs/proposal.html +13 -106
- data/docs/proposal.md +3 -3
- data/docs/todo.html +38 -28
- data/lib/maruku.rb +77 -11
- data/lib/maruku/attributes.rb +186 -0
- data/lib/maruku/defaults.rb +40 -0
- data/lib/maruku/errors_management.rb +55 -39
- data/lib/maruku/helpers.rb +156 -72
- data/lib/maruku/input/charsource.rb +319 -0
- data/lib/maruku/{html_helper.rb → input/html_helper.rb} +30 -9
- data/lib/maruku/input/linesource.rb +111 -0
- data/lib/maruku/input/parse_block.rb +562 -0
- data/lib/maruku/{parse_doc.rb → input/parse_doc.rb} +60 -28
- data/lib/maruku/{parse_span_better.rb → input/parse_span_better.rb} +226 -256
- data/lib/maruku/input/type_detection.rb +137 -0
- data/lib/maruku/maruku.rb +33 -0
- data/lib/maruku/{to_html.rb → output/to_html.rb} +151 -132
- data/lib/maruku/{to_latex.rb → output/to_latex.rb} +31 -35
- data/lib/maruku/{to_latex_entities.rb → output/to_latex_entities.rb} +25 -3
- data/lib/maruku/output/to_latex_strings.rb +64 -0
- data/lib/maruku/output/to_markdown.rb +164 -0
- data/lib/maruku/{to_s.rb → output/to_s.rb} +6 -0
- data/lib/maruku/string_utils.rb +12 -181
- data/lib/maruku/structures.rb +91 -67
- data/lib/maruku/structures_inspect.rb +78 -0
- data/lib/maruku/structures_iterators.rb +24 -2
- data/lib/maruku/tests/benchmark.rb +41 -9
- data/lib/maruku/tests/new_parser.rb +317 -286
- data/lib/maruku/tests/tests.rb +20 -0
- data/lib/maruku/toc.rb +64 -64
- data/lib/maruku/usage/example1.rb +33 -0
- data/lib/maruku/version.rb +8 -2
- data/tests/unittest/abbreviations.md +27 -16
- data/tests/unittest/attributes/attributes.md +89 -0
- data/tests/unittest/attributes/circular.md +51 -0
- data/tests/unittest/attributes/default.md +47 -0
- data/tests/unittest/blank.md +10 -6
- data/tests/unittest/blanks_in_code.md +26 -26
- data/tests/unittest/code.md +9 -9
- data/tests/unittest/code2.md +12 -13
- data/tests/unittest/code3.md +34 -34
- data/tests/unittest/easy.md +9 -7
- data/tests/unittest/email.md +9 -7
- data/tests/unittest/encoding/iso-8859-1.md +41 -4
- data/tests/unittest/encoding/utf-8.md +6 -5
- data/tests/unittest/entities.md +52 -80
- data/tests/unittest/escaping.md +47 -35
- data/tests/unittest/extra_dl.md +19 -29
- data/tests/unittest/extra_header_id.md +31 -24
- data/tests/unittest/extra_table1.md +14 -32
- data/tests/unittest/footnotes.md +58 -42
- data/tests/unittest/headers.md +11 -11
- data/tests/unittest/hrule.md +14 -24
- data/tests/unittest/images.md +41 -26
- data/tests/unittest/inline_html.md +104 -56
- data/tests/unittest/inline_html2.md +38 -0
- data/tests/unittest/links.md +74 -33
- data/tests/unittest/list1.md +18 -15
- data/tests/unittest/list2.md +31 -13
- data/tests/unittest/list3.md +29 -28
- data/tests/unittest/list4.md +103 -12
- data/tests/unittest/lists.md +86 -53
- data/tests/unittest/lists6.md +53 -0
- data/tests/unittest/lists7.md +31 -0
- data/tests/unittest/lists_after_paragraph.md +105 -71
- data/tests/unittest/lists_ol.md +149 -73
- data/tests/unittest/misc_sw.md +366 -326
- data/tests/unittest/notyet/escape.md +10 -10
- data/tests/unittest/notyet/header_after_par.md +20 -14
- data/tests/unittest/notyet/ticks.md +8 -35
- data/tests/unittest/notyet/triggering.md +72 -45
- data/tests/unittest/olist.md +78 -0
- data/tests/unittest/one.md +5 -3
- data/tests/unittest/paragraph.md +5 -3
- data/tests/unittest/paragraph_rules/dont_merge_ref.md +15 -9
- data/tests/unittest/paragraph_rules/tab_is_blank.md +9 -5
- data/tests/unittest/paragraphs.md +21 -26
- data/tests/unittest/recover/recover_links.md +6 -5
- data/tests/unittest/references/long_example.md +39 -30
- data/tests/unittest/references/spaces_and_numbers.md +2 -2
- data/tests/unittest/syntax_hl.md +33 -31
- data/tests/unittest/test.md +4 -6
- data/tests/unittest/wrapping.md +43 -26
- metadata +160 -139
- data/docs/markdown_extra2.html +0 -87
- data/docs/markdown_extra2.md +0 -83
- data/docs/markdown_syntax_2.html +0 -152
- data/lib/maruku/parse_block.rb +0 -564
- data/lib/maruku/parse_span.rb +0 -451
- data/lib/maruku/to_latex_strings.rb +0 -59
- data/lib/maruku/to_markdown.rb +0 -110
- data/lib/test.rb +0 -29
data/docs/markdown_syntax.html
CHANGED
|
@@ -1,95 +1,79 @@
|
|
|
1
1
|
<?xml version='1.0' encoding='utf-8'?>
|
|
2
2
|
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
|
|
3
3
|
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
|
|
4
|
-
<html lang='en' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>
|
|
5
|
-
<head>
|
|
6
|
-
<title>Markdown: Syntax</title>
|
|
7
|
-
|
|
8
|
-
<link href='style.css' rel='stylesheet' type='text/css' />
|
|
9
|
-
</head>
|
|
10
|
-
<body>
|
|
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>Markdown: Syntax</title><link href='style.css' rel='stylesheet' type='text/css' /></head><body>
|
|
11
5
|
<h1 id='markdown_syntax'>Markdown: Syntax</h1>
|
|
6
|
+
<ul id='ProjectSubmenu'>
|
|
7
|
+
<li><a href='/projects/markdown/' title='Markdown Project Page'>Main</a></li>
|
|
8
|
+
<li><a href='/projects/markdown/basics' title='Markdown Basics'>Basics</a></li>
|
|
9
|
+
<li><a class='selected' title='Markdown Syntax Documentation'>Syntax</a></li>
|
|
10
|
+
<li><a href='/projects/markdown/license' title='Pricing and License Information'>License</a></li>
|
|
11
|
+
<li><a href='/projects/markdown/dingus' title='Online Markdown Web Form'>Dingus</a></li>
|
|
12
|
+
</ul>
|
|
13
|
+
<ul>
|
|
14
|
+
<li>
|
|
15
|
+
<p><a href='#overview'>Overview</a></p>
|
|
12
16
|
|
|
13
|
-
<
|
|
17
|
+
<ul>
|
|
18
|
+
<li><a href='#philosophy'>Philosophy</a></li>
|
|
14
19
|
|
|
15
|
-
<
|
|
20
|
+
<li><a href='#html'>Inline HTML</a></li>
|
|
16
21
|
|
|
17
|
-
<
|
|
22
|
+
<li><a href='#autoescape'>Automatic Escaping for Special Characters</a></li>
|
|
23
|
+
</ul>
|
|
24
|
+
</li>
|
|
18
25
|
|
|
19
|
-
<
|
|
20
|
-
<p><a href='
|
|
26
|
+
<li>
|
|
27
|
+
<p><a href='#block'>Block Elements</a></p>
|
|
21
28
|
|
|
22
|
-
<
|
|
29
|
+
<ul>
|
|
30
|
+
<li><a href='#p'>Paragraphs and Line Breaks</a></li>
|
|
23
31
|
|
|
24
|
-
<
|
|
25
|
-
</blockquote>
|
|
32
|
+
<li><a href='#header'>Headers</a></li>
|
|
26
33
|
|
|
27
|
-
<
|
|
34
|
+
<li><a href='#blockquote'>Blockquotes</a></li>
|
|
28
35
|
|
|
29
|
-
<
|
|
30
|
-
<ul style='list-style: none;'>
|
|
31
|
-
<li><span class='maruku_section_number'>1. </span><a href='#overview'>Overview</a>
|
|
32
|
-
<ul style='list-style: none;'>
|
|
33
|
-
<li><span class='maruku_section_number'>1.1. </span><a href='#philosophy'>Philosophy</a></li>
|
|
36
|
+
<li><a href='#list'>Lists</a></li>
|
|
34
37
|
|
|
35
|
-
<li><
|
|
38
|
+
<li><a href='#precode'>Code Blocks</a></li>
|
|
36
39
|
|
|
37
|
-
<li><
|
|
40
|
+
<li><a href='#hr'>Horizontal Rules</a></li>
|
|
38
41
|
</ul>
|
|
39
42
|
</li>
|
|
40
43
|
|
|
41
|
-
<li
|
|
42
|
-
<
|
|
43
|
-
<li><span class='maruku_section_number'>2.1. </span><a href='#p'>Paragraphs and Line Breaks</a></li>
|
|
44
|
-
|
|
45
|
-
<li><span class='maruku_section_number'>2.2. </span><a href='#header'>Headers</a></li>
|
|
44
|
+
<li>
|
|
45
|
+
<p><a href='#span'>Span Elements</a></p>
|
|
46
46
|
|
|
47
|
-
<
|
|
47
|
+
<ul>
|
|
48
|
+
<li><a href='#link'>Links</a></li>
|
|
48
49
|
|
|
49
|
-
<li><
|
|
50
|
+
<li><a href='#em'>Emphasis</a></li>
|
|
50
51
|
|
|
51
|
-
<li><
|
|
52
|
+
<li><a href='#code'>Code</a></li>
|
|
52
53
|
|
|
53
|
-
<li><
|
|
54
|
+
<li><a href='#img'>Images</a></li>
|
|
54
55
|
</ul>
|
|
55
56
|
</li>
|
|
56
57
|
|
|
57
|
-
<li
|
|
58
|
-
<
|
|
59
|
-
<li><span class='maruku_section_number'>3.1. </span><a href='#link'>Links</a></li>
|
|
60
|
-
|
|
61
|
-
<li><span class='maruku_section_number'>3.2. </span><a href='#em'>Emphasis</a></li>
|
|
58
|
+
<li>
|
|
59
|
+
<p><a href='#misc'>Miscellaneous</a></p>
|
|
62
60
|
|
|
63
|
-
<
|
|
64
|
-
|
|
65
|
-
<li><span class='maruku_section_number'>3.4. </span><a href='#img'>Images</a></li>
|
|
66
|
-
</ul>
|
|
67
|
-
</li>
|
|
68
|
-
|
|
69
|
-
<li><span class='maruku_section_number'>4. </span><a href='#misc'>Miscellaneous</a>
|
|
70
|
-
<ul style='list-style: none;'>
|
|
71
|
-
<li><span class='maruku_section_number'>4.1. </span><a href='#autolink'>Automatic Links</a></li>
|
|
61
|
+
<ul>
|
|
62
|
+
<li><a href='#backslash'>Backslash Escapes</a></li>
|
|
72
63
|
|
|
73
|
-
<li><
|
|
64
|
+
<li><a href='#autolink'>Automatic Links</a></li>
|
|
74
65
|
</ul>
|
|
75
66
|
</li>
|
|
76
67
|
</ul>
|
|
77
|
-
</div>
|
|
78
|
-
|
|
79
|
-
<hr />
|
|
80
|
-
|
|
81
|
-
<h2 id='overview'><span class='maruku_section_number'>1. </span>Overview</h2>
|
|
82
|
-
|
|
83
|
-
<h3 id='philosophy'><span class='maruku_section_number'>1.1. </span>Philosophy</h3>
|
|
84
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 '.text' to the URL</a>.</p>
|
|
70
|
+
<hr /><h2 id='overview'>Overview</h2><h3 id='philosophy'>Philosophy</h3>
|
|
85
71
|
<p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.</p>
|
|
86
72
|
|
|
87
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>
|
|
88
74
|
|
|
89
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>
|
|
90
|
-
|
|
91
|
-
<h3 id='html'><span class='maruku_section_number'>1.2. </span>Inline HTML</h3>
|
|
92
|
-
|
|
76
|
+
<h3 id='html'>Inline HTML</h3>
|
|
93
77
|
<p>Markdown's syntax is intended for one purpose: to be used as a format for <em>writing</em> for the web.</p>
|
|
94
78
|
|
|
95
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>
|
|
@@ -99,117 +83,86 @@
|
|
|
99
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>
|
|
100
84
|
|
|
101
85
|
<p>For example, to add an HTML table to a Markdown article:</p>
|
|
86
|
+
<pre><code>This is a regular paragraph.
|
|
102
87
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
<span class='punct'></</span><span class='tag'>tr</span><span class='punct'>></span>
|
|
109
|
-
<span class='punct'></</span><span class='tag'>table</span><span class='punct'>></span>
|
|
110
|
-
|
|
111
|
-
This is another regular paragraph.</pre>
|
|
88
|
+
<table>
|
|
89
|
+
<tr>
|
|
90
|
+
<td>Foo</td>
|
|
91
|
+
</tr>
|
|
92
|
+
</table>
|
|
112
93
|
|
|
94
|
+
This is another regular paragraph.
|
|
95
|
+
</code></pre>
|
|
113
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>
|
|
114
97
|
|
|
115
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>
|
|
116
99
|
|
|
117
100
|
<p>Unlike block-level HTML tags, Markdown syntax <em>is</em> processed within span-level tags.</p>
|
|
118
|
-
|
|
119
|
-
<h3 id='autoescape'><span class='maruku_section_number'>1.3. </span>Automatic Escaping for Special Characters</h3>
|
|
120
|
-
|
|
101
|
+
<h3 id='autoescape'>Automatic Escaping for Special Characters</h3>
|
|
121
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>
|
|
122
103
|
|
|
123
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>
|
|
124
|
-
|
|
125
105
|
<pre><code>http://images.google.com/images?num=30&q=larry+bird
|
|
126
106
|
</code></pre>
|
|
127
|
-
|
|
128
107
|
<p>you need to encode the URL as:</p>
|
|
129
|
-
|
|
130
108
|
<pre><code>http://images.google.com/images?num=30&amp;q=larry+bird
|
|
131
109
|
</code></pre>
|
|
132
|
-
|
|
133
110
|
<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>
|
|
134
111
|
|
|
135
112
|
<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>
|
|
136
113
|
|
|
137
114
|
<p>So, if you want to include a copyright symbol in your article, you can write:</p>
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
115
|
+
<pre><code>&copy;
|
|
116
|
+
</code></pre>
|
|
141
117
|
<p>and Markdown will leave it alone. But if you write:</p>
|
|
142
|
-
|
|
143
118
|
<pre><code>AT&T
|
|
144
119
|
</code></pre>
|
|
145
|
-
|
|
146
120
|
<p>Markdown will translate it to:</p>
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
121
|
+
<pre><code>AT&amp;T
|
|
122
|
+
</code></pre>
|
|
150
123
|
<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>
|
|
151
|
-
|
|
152
124
|
<pre><code>4 < 5
|
|
153
125
|
</code></pre>
|
|
154
|
-
|
|
155
126
|
<p>Markdown will translate it to:</p>
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
127
|
+
<pre><code>4 &lt; 5
|
|
128
|
+
</code></pre>
|
|
159
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>
|
|
160
|
-
|
|
161
|
-
<
|
|
162
|
-
|
|
163
|
-
<h2 id='block'><span class='maruku_section_number'>2. </span>Block Elements</h2>
|
|
164
|
-
|
|
165
|
-
<h3 id='p'><span class='maruku_section_number'>2.1. </span>Paragraphs and Line Breaks</h3>
|
|
166
|
-
|
|
167
|
-
<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 intended with spaces or tabs.</p>
|
|
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 -- a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.</p>
|
|
168
132
|
|
|
169
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>
|
|
170
134
|
|
|
171
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>
|
|
172
136
|
|
|
173
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>
|
|
174
|
-
|
|
175
|
-
<h3 id='header'><span class='maruku_section_number'>2.2. </span>Headers</h3>
|
|
176
|
-
|
|
138
|
+
<h3 id='header'>Headers</h3>
|
|
177
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>
|
|
178
140
|
|
|
179
141
|
<p>Setext-style headers are "underlined" using equal signs (for first-level headers) and dashes (for second-level headers). For example:</p>
|
|
180
|
-
|
|
181
142
|
<pre><code>This is an H1
|
|
182
143
|
=============
|
|
183
144
|
|
|
184
145
|
This is an H2
|
|
185
146
|
-------------
|
|
186
147
|
</code></pre>
|
|
187
|
-
|
|
188
148
|
<p>Any number of underlining <code>=</code>'s or <code>-</code>'s will work.</p>
|
|
189
149
|
|
|
190
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>
|
|
191
|
-
|
|
192
151
|
<pre><code># This is an H1
|
|
193
152
|
|
|
194
153
|
## This is an H2
|
|
195
154
|
|
|
196
155
|
###### This is an H6
|
|
197
156
|
</code></pre>
|
|
198
|
-
|
|
199
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>
|
|
200
|
-
|
|
201
158
|
<pre><code># This is an H1 #
|
|
202
159
|
|
|
203
160
|
## This is an H2 ##
|
|
204
161
|
|
|
205
162
|
### This is an H3 ######
|
|
206
163
|
|
|
207
|
-
</code></pre>
|
|
208
|
-
|
|
209
|
-
<h3 id='blockquote'><span class='maruku_section_number'>2.3. </span>Blockquotes</h3>
|
|
210
|
-
|
|
164
|
+
</code></pre><h3 id='blockquote'>Blockquotes</h3>
|
|
211
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>
|
|
212
|
-
|
|
213
166
|
<pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
|
214
167
|
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
|
215
168
|
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
|
@@ -217,9 +170,7 @@ This is an H2
|
|
|
217
170
|
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
|
218
171
|
> id sem consectetuer libero luctus adipiscing.
|
|
219
172
|
</code></pre>
|
|
220
|
-
|
|
221
173
|
<p>Markdown allows you to be lazy and only put the <code>></code> before the first line of a hard-wrapped paragraph:</p>
|
|
222
|
-
|
|
223
174
|
<pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
|
224
175
|
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
|
225
176
|
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
|
@@ -227,18 +178,14 @@ Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
|
|
227
178
|
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
|
228
179
|
id sem consectetuer libero luctus adipiscing.
|
|
229
180
|
</code></pre>
|
|
230
|
-
|
|
231
181
|
<p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of <code>></code>:</p>
|
|
232
|
-
|
|
233
182
|
<pre><code>> This is the first level of quoting.
|
|
234
183
|
>
|
|
235
184
|
> > This is nested blockquote.
|
|
236
185
|
>
|
|
237
186
|
> Back to the first level.
|
|
238
187
|
</code></pre>
|
|
239
|
-
|
|
240
188
|
<p>Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:</p>
|
|
241
|
-
|
|
242
189
|
<pre><code>> ## This is a header.
|
|
243
190
|
>
|
|
244
191
|
> 1. This is the first list item.
|
|
@@ -248,63 +195,47 @@ id sem consectetuer libero luctus adipiscing.
|
|
|
248
195
|
>
|
|
249
196
|
> return shell_exec("echo $input | $markdown_script");
|
|
250
197
|
</code></pre>
|
|
251
|
-
|
|
252
198
|
<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>
|
|
253
|
-
|
|
254
|
-
<h3 id='list'><span class='maruku_section_number'>2.4. </span>Lists</h3>
|
|
255
|
-
|
|
199
|
+
<h3 id='list'>Lists</h3>
|
|
256
200
|
<p>Markdown supports ordered (numbered) and unordered (bulleted) lists.</p>
|
|
257
201
|
|
|
258
202
|
<p>Unordered lists use asterisks, pluses, and hyphens -- interchangably -- as list markers:</p>
|
|
259
|
-
|
|
260
203
|
<pre><code>* Red
|
|
261
204
|
* Green
|
|
262
205
|
* Blue
|
|
263
206
|
</code></pre>
|
|
264
|
-
|
|
265
207
|
<p>is equivalent to:</p>
|
|
266
|
-
|
|
267
208
|
<pre><code>+ Red
|
|
268
209
|
+ Green
|
|
269
210
|
+ Blue
|
|
270
211
|
</code></pre>
|
|
271
|
-
|
|
272
212
|
<p>and:</p>
|
|
273
|
-
|
|
274
213
|
<pre><code>- Red
|
|
275
214
|
- Green
|
|
276
215
|
- Blue
|
|
277
216
|
</code></pre>
|
|
278
|
-
|
|
279
217
|
<p>Ordered lists use numbers followed by periods:</p>
|
|
280
|
-
|
|
281
218
|
<pre><code>1. Bird
|
|
282
219
|
2. McHale
|
|
283
220
|
3. Parish
|
|
284
221
|
</code></pre>
|
|
285
|
-
|
|
286
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>
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
223
|
+
<pre><code><ol>
|
|
224
|
+
<li>Bird</li>
|
|
225
|
+
<li>McHale</li>
|
|
226
|
+
<li>Parish</li>
|
|
227
|
+
</ol>
|
|
228
|
+
</code></pre>
|
|
294
229
|
<p>If you instead wrote the list in Markdown like this:</p>
|
|
295
|
-
|
|
296
230
|
<pre><code>1. Bird
|
|
297
231
|
1. McHale
|
|
298
232
|
1. Parish
|
|
299
233
|
</code></pre>
|
|
300
|
-
|
|
301
234
|
<p>or even:</p>
|
|
302
|
-
|
|
303
235
|
<pre><code>3. Bird
|
|
304
236
|
1. McHale
|
|
305
237
|
8. Parish
|
|
306
238
|
</code></pre>
|
|
307
|
-
|
|
308
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>
|
|
309
240
|
|
|
310
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>
|
|
@@ -312,52 +243,41 @@ id sem consectetuer libero luctus adipiscing.
|
|
|
312
243
|
<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>
|
|
313
244
|
|
|
314
245
|
<p>To make lists look nice, you can wrap items with hanging indents:</p>
|
|
315
|
-
|
|
316
246
|
<pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
317
247
|
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
|
318
248
|
viverra nec, fringilla in, laoreet vitae, risus.
|
|
319
249
|
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
|
320
250
|
Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
321
251
|
</code></pre>
|
|
322
|
-
|
|
323
252
|
<p>But if you want to be lazy, you don't have to:</p>
|
|
324
|
-
|
|
325
253
|
<pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
326
254
|
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
|
327
255
|
viverra nec, fringilla in, laoreet vitae, risus.
|
|
328
256
|
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
|
329
257
|
Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
330
258
|
</code></pre>
|
|
331
|
-
|
|
332
259
|
<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>
|
|
333
|
-
|
|
334
260
|
<pre><code>* Bird
|
|
335
261
|
* Magic
|
|
336
262
|
</code></pre>
|
|
337
|
-
|
|
338
263
|
<p>will turn into:</p>
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
264
|
+
<pre><code><ul>
|
|
265
|
+
<li>Bird</li>
|
|
266
|
+
<li>Magic</li>
|
|
267
|
+
</ul>
|
|
268
|
+
</code></pre>
|
|
345
269
|
<p>But this:</p>
|
|
346
|
-
|
|
347
270
|
<pre><code>* Bird
|
|
348
271
|
|
|
349
272
|
* Magic
|
|
350
273
|
</code></pre>
|
|
351
|
-
|
|
352
274
|
<p>will turn into:</p>
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
275
|
+
<pre><code><ul>
|
|
276
|
+
<li><p>Bird</p></li>
|
|
277
|
+
<li><p>Magic</p></li>
|
|
278
|
+
</ul>
|
|
279
|
+
</code></pre>
|
|
359
280
|
<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>
|
|
360
|
-
|
|
361
281
|
<pre><code>1. This is a list item with two paragraphs. Lorem ipsum dolor
|
|
362
282
|
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
|
|
363
283
|
mi posuere lectus.
|
|
@@ -368,9 +288,7 @@ Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
|
368
288
|
|
|
369
289
|
2. Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
370
290
|
</code></pre>
|
|
371
|
-
|
|
372
291
|
<p>It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:</p>
|
|
373
|
-
|
|
374
292
|
<pre><code>* This is a list item with two paragraphs.
|
|
375
293
|
|
|
376
294
|
This is the second paragraph in the list item. You're
|
|
@@ -379,93 +297,70 @@ sit amet, consectetuer adipiscing elit.
|
|
|
379
297
|
|
|
380
298
|
* Another item in the same list.
|
|
381
299
|
</code></pre>
|
|
382
|
-
|
|
383
300
|
<p>To put a blockquote within a list item, the blockquote's <code>></code> delimiters need to be indented:</p>
|
|
384
|
-
|
|
385
301
|
<pre><code>* A list item with a blockquote:
|
|
386
302
|
|
|
387
303
|
> This is a blockquote
|
|
388
304
|
> inside a list item.
|
|
389
305
|
</code></pre>
|
|
390
|
-
|
|
391
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>
|
|
392
|
-
|
|
393
307
|
<pre><code>* A list item with a code block:
|
|
394
308
|
|
|
395
309
|
<code goes here>
|
|
396
310
|
|
|
397
311
|
</code></pre>
|
|
398
|
-
|
|
399
312
|
<p>It's worth noting that it's possible to trigger an ordered list by accident, by writing something like this:</p>
|
|
400
|
-
|
|
401
313
|
<pre><code>1986. What a great season.
|
|
402
314
|
</code></pre>
|
|
403
|
-
|
|
404
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>
|
|
316
|
+
<pre><code>1986\. What a great season.
|
|
405
317
|
|
|
406
|
-
<pre><code>1986\\. What a great season.
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
</code></pre>
|
|
410
|
-
|
|
411
|
-
<h3 id='precode'><span class='maruku_section_number'>2.5. </span>Code Blocks</h3>
|
|
412
318
|
|
|
319
|
+
</code></pre><h3 id='precode'>Code Blocks</h3>
|
|
413
320
|
<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>
|
|
414
321
|
|
|
415
322
|
<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>
|
|
416
|
-
|
|
417
323
|
<pre><code>This is a normal paragraph:
|
|
418
324
|
|
|
419
325
|
This is a code block.
|
|
420
326
|
</code></pre>
|
|
421
|
-
|
|
422
327
|
<p>Markdown will generate:</p>
|
|
328
|
+
<pre><code><p>This is a normal paragraph:</p>
|
|
423
329
|
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
<span class='punct'></</span><span class='tag'>code</span><span class='punct'>></</span><span class='tag'>pre</span><span class='punct'>></span></pre>
|
|
428
|
-
|
|
330
|
+
<pre><code>This is a code block.
|
|
331
|
+
</code></pre>
|
|
332
|
+
</code></pre>
|
|
429
333
|
<p>One level of indentation -- 4 spaces or 1 tab -- is removed from each line of the code block. For example, this:</p>
|
|
430
|
-
|
|
431
334
|
<pre><code>Here is an example of AppleScript:
|
|
432
335
|
|
|
433
336
|
tell application "Foo"
|
|
434
337
|
beep
|
|
435
338
|
end tell
|
|
436
339
|
</code></pre>
|
|
437
|
-
|
|
438
340
|
<p>will turn into:</p>
|
|
341
|
+
<pre><code><p>Here is an example of AppleScript:</p>
|
|
439
342
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
<span class='punct'><</span><span class='tag'>pre</span><span class='punct'>><</span><span class='tag'>code</span><span class='punct'>></span>tell application "Foo"
|
|
343
|
+
<pre><code>tell application "Foo"
|
|
443
344
|
beep
|
|
444
345
|
end tell
|
|
445
|
-
|
|
446
|
-
|
|
346
|
+
</code></pre>
|
|
347
|
+
</code></pre>
|
|
447
348
|
<p>A code block continues until it reaches a line that is not indented (or the end of the article).</p>
|
|
448
349
|
|
|
449
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>
|
|
450
|
-
|
|
451
351
|
<pre><code> <div class="footer">
|
|
452
352
|
&copy; 2004 Foo Corporation
|
|
453
353
|
</div>
|
|
454
354
|
</code></pre>
|
|
455
|
-
|
|
456
355
|
<p>will turn into:</p>
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
356
|
+
<pre><code><pre><code>&lt;div class="footer"&gt;
|
|
357
|
+
&amp;copy; 2004 Foo Corporation
|
|
358
|
+
&lt;/div&gt;
|
|
359
|
+
</code></pre>
|
|
360
|
+
</code></pre>
|
|
463
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>
|
|
464
|
-
|
|
465
|
-
<
|
|
466
|
-
|
|
467
|
-
<p>You can produce a horizontal rule tag (<code><hr /></code>) by placing three or more hyphens or asterisks 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>
|
|
468
|
-
|
|
362
|
+
<h3 id='hr'>Horizontal Rules</h3>
|
|
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>
|
|
469
364
|
<pre><code>* * *
|
|
470
365
|
|
|
471
366
|
***
|
|
@@ -476,57 +371,39 @@ end tell
|
|
|
476
371
|
|
|
477
372
|
---------------------------------------
|
|
478
373
|
|
|
479
|
-
</code></pre>
|
|
480
|
-
|
|
481
|
-
<hr />
|
|
482
|
-
|
|
483
|
-
<h2 id='span'><span class='maruku_section_number'>3. </span>Span Elements</h2>
|
|
484
|
-
|
|
485
|
-
<h3 id='link'><span class='maruku_section_number'>3.1. </span>Links</h3>
|
|
486
|
-
|
|
374
|
+
</code></pre><hr /><h2 id='span'>Span Elements</h2><h3 id='link'>Links</h3>
|
|
487
375
|
<p>Markdown supports two style of links: <em>inline</em> and <em>reference</em>.</p>
|
|
488
376
|
|
|
489
377
|
<p>In both styles, the link text is delimited by square brackets.</p>
|
|
490
378
|
|
|
491
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>
|
|
492
|
-
|
|
493
380
|
<pre><code>This is [an example](http://example.com/ "Title") inline link.
|
|
494
381
|
|
|
495
382
|
[This link](http://example.net/) has no title attribute.
|
|
496
383
|
</code></pre>
|
|
497
|
-
|
|
498
384
|
<p>Will produce:</p>
|
|
385
|
+
<pre><code><p>This is <a href="http://example.com/" title="Title">
|
|
386
|
+
an example</a> inline link.</p>
|
|
499
387
|
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
<span class='punct'><</span><span class='tag'>p</span><span class='punct'>><</span><span class='tag'>a</span> <span class='attribute'>href</span><span class='punct'>="</span><span class='string'>http://example.net/</span><span class='punct'>"></span>This link<span class='punct'></</span><span class='tag'>a</span><span class='punct'>></span> has no
|
|
504
|
-
title attribute.<span class='punct'></</span><span class='tag'>p</span><span class='punct'>></span></pre>
|
|
505
|
-
|
|
388
|
+
<p><a href="http://example.net/">This link</a> has no
|
|
389
|
+
title attribute.</p>
|
|
390
|
+
</code></pre>
|
|
506
391
|
<p>If you're referring to a local resource on the same server, you can use relative paths:</p>
|
|
507
|
-
|
|
508
392
|
<pre><code>See my [About](/about/) page for details.
|
|
509
393
|
</code></pre>
|
|
510
|
-
|
|
511
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>
|
|
512
|
-
|
|
513
395
|
<pre><code>This is [an example][id] reference-style link.
|
|
514
396
|
</code></pre>
|
|
515
|
-
|
|
516
397
|
<p>You can optionally use a space to separate the sets of brackets:</p>
|
|
517
|
-
|
|
518
398
|
<pre><code>This is [an example] [id] reference-style link.
|
|
519
399
|
</code></pre>
|
|
520
|
-
|
|
521
400
|
<p>Then, anywhere in the document, you define your link label like this, on a line by itself:</p>
|
|
522
|
-
|
|
523
401
|
<pre><code>[id]: http://example.com/ "Optional Title Here"
|
|
524
402
|
</code></pre>
|
|
525
|
-
|
|
526
403
|
<p>That is:</p>
|
|
527
404
|
|
|
528
405
|
<ul>
|
|
529
|
-
<li>Square brackets containing the link identifier (optionally indented from the left margin using
|
|
406
|
+
<li>Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);</li>
|
|
530
407
|
|
|
531
408
|
<li>followed by a colon;</li>
|
|
532
409
|
|
|
@@ -538,59 +415,42 @@ title attribute.<span class='punct'></</span><span class='tag'>p</span><span
|
|
|
538
415
|
</ul>
|
|
539
416
|
|
|
540
417
|
<p>The following three link definitions are equivalent:</p>
|
|
541
|
-
|
|
542
418
|
<pre><code>[foo]: http://example.com/ "Optional Title Here"
|
|
543
419
|
[foo]: http://example.com/ 'Optional Title Here'
|
|
544
420
|
[foo]: http://example.com/ (Optional Title Here)
|
|
545
421
|
</code></pre>
|
|
546
|
-
|
|
547
|
-
<p><strong>Note:</strong> There is a known bug in Markdown 1.0.1 which prevents single quotes from being used to delimit link titles.</p>
|
|
422
|
+
<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>
|
|
548
423
|
|
|
549
424
|
<p>The link URL may, optionally, be surrounded by angle brackets:</p>
|
|
550
|
-
|
|
551
425
|
<pre><code>[id]: <http://example.com/> "Optional Title Here"
|
|
552
426
|
</code></pre>
|
|
553
|
-
|
|
554
427
|
<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>
|
|
555
|
-
|
|
556
428
|
<pre><code>[id]: http://example.com/longish/path/to/resource/here
|
|
557
429
|
"Optional Title Here"
|
|
558
430
|
</code></pre>
|
|
559
|
-
|
|
560
431
|
<p>Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.</p>
|
|
561
432
|
|
|
562
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>
|
|
563
|
-
|
|
564
434
|
<pre><code>[link text][a]
|
|
565
435
|
[link text][A]
|
|
566
436
|
</code></pre>
|
|
567
|
-
|
|
568
437
|
<p>are equivalent.</p>
|
|
569
438
|
|
|
570
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>
|
|
571
|
-
|
|
572
440
|
<pre><code>[Google][]
|
|
573
441
|
</code></pre>
|
|
574
|
-
|
|
575
442
|
<p>And then define the link:</p>
|
|
576
|
-
|
|
577
443
|
<pre><code>[Google]: http://google.com/
|
|
578
444
|
</code></pre>
|
|
579
|
-
|
|
580
445
|
<p>Because link names may contain spaces, this shortcut even works for multiple words in the link text:</p>
|
|
581
|
-
|
|
582
446
|
<pre><code>Visit [Daring Fireball][] for more information.
|
|
583
447
|
</code></pre>
|
|
584
|
-
|
|
585
448
|
<p>And then define the link:</p>
|
|
586
|
-
|
|
587
449
|
<pre><code>[Daring Fireball]: http://daringfireball.net/
|
|
588
450
|
</code></pre>
|
|
589
|
-
|
|
590
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>
|
|
591
452
|
|
|
592
453
|
<p>Here's an example of reference links in action:</p>
|
|
593
|
-
|
|
594
454
|
<pre><code>I get 10 times more traffic from [Google] [1] than from
|
|
595
455
|
[Yahoo] [2] or [MSN] [3].
|
|
596
456
|
|
|
@@ -598,9 +458,7 @@ title attribute.<span class='punct'></</span><span class='tag'>p</span><span
|
|
|
598
458
|
[2]: http://search.yahoo.com/ "Yahoo Search"
|
|
599
459
|
[3]: http://search.msn.com/ "MSN Search"
|
|
600
460
|
</code></pre>
|
|
601
|
-
|
|
602
461
|
<p>Using the implicit link name shortcut, you could instead write:</p>
|
|
603
|
-
|
|
604
462
|
<pre><code>I get 10 times more traffic from [Google][] than from
|
|
605
463
|
[Yahoo][] or [MSN][].
|
|
606
464
|
|
|
@@ -608,30 +466,22 @@ title attribute.<span class='punct'></</span><span class='tag'>p</span><span
|
|
|
608
466
|
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
|
|
609
467
|
[msn]: http://search.msn.com/ "MSN Search"
|
|
610
468
|
</code></pre>
|
|
611
|
-
|
|
612
469
|
<p>Both of the above examples will produce the following HTML output:</p>
|
|
613
|
-
|
|
614
470
|
<pre><code><p>I get 10 times more traffic from <a href="http://google.com/"
|
|
615
471
|
title="Google">Google</a> than from
|
|
616
472
|
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
|
|
617
473
|
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
|
|
618
474
|
</code></pre>
|
|
619
|
-
|
|
620
475
|
<p>For comparison, here is the same paragraph written using Markdown's inline link style:</p>
|
|
621
|
-
|
|
622
476
|
<pre><code>I get 10 times more traffic from [Google](http://google.com/ "Google")
|
|
623
477
|
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
|
|
624
478
|
[MSN](http://search.msn.com/ "MSN Search").
|
|
625
479
|
</code></pre>
|
|
626
|
-
|
|
627
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>
|
|
628
481
|
|
|
629
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>
|
|
630
|
-
|
|
631
|
-
<h3 id='em'><span class='maruku_section_number'>3.2. </span>Emphasis</h3>
|
|
632
|
-
|
|
483
|
+
<h3 id='em'>Emphasis</h3>
|
|
633
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>
|
|
634
|
-
|
|
635
485
|
<pre><code>*single asterisks*
|
|
636
486
|
|
|
637
487
|
_single underscores_
|
|
@@ -640,90 +490,73 @@ _single underscores_
|
|
|
640
490
|
|
|
641
491
|
__double underscores__
|
|
642
492
|
</code></pre>
|
|
643
|
-
|
|
644
493
|
<p>will produce:</p>
|
|
494
|
+
<pre><code><em>single asterisks</em>
|
|
645
495
|
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
<span class='punct'><</span><span class='tag'>em</span><span class='punct'>></span>single underscores<span class='punct'></</span><span class='tag'>em</span><span class='punct'>></span>
|
|
649
|
-
|
|
650
|
-
<span class='punct'><</span><span class='tag'>strong</span><span class='punct'>></span>double asterisks<span class='punct'></</span><span class='tag'>strong</span><span class='punct'>></span>
|
|
496
|
+
<em>single underscores</em>
|
|
651
497
|
|
|
652
|
-
|
|
498
|
+
<strong>double asterisks</strong>
|
|
653
499
|
|
|
500
|
+
<strong>double underscores</strong>
|
|
501
|
+
</code></pre>
|
|
654
502
|
<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>
|
|
655
503
|
|
|
656
504
|
<p>Emphasis can be used in the middle of a word:</p>
|
|
657
|
-
|
|
658
505
|
<pre><code>un*fucking*believable
|
|
659
506
|
</code></pre>
|
|
660
|
-
|
|
661
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>
|
|
662
508
|
|
|
663
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>
|
|
664
|
-
|
|
665
510
|
<pre><code>\*this text is surrounded by literal asterisks\*
|
|
666
511
|
|
|
667
512
|
|
|
668
|
-
</code></pre>
|
|
669
|
-
|
|
670
|
-
<h3 id='code'><span class='maruku_section_number'>3.3. </span>Code</h3>
|
|
671
|
-
|
|
513
|
+
</code></pre><h3 id='code'>Code</h3>
|
|
672
514
|
<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>
|
|
673
|
-
|
|
674
515
|
<pre><code>Use the `printf()` function.
|
|
675
516
|
</code></pre>
|
|
676
|
-
|
|
677
517
|
<p>will produce:</p>
|
|
678
|
-
|
|
679
|
-
<pre class='xml'><span class='punct'><</span><span class='tag'>p</span><span class='punct'>></span>Use the <span class='punct'><</span><span class='tag'>code</span><span class='punct'>></span>printf()<span class='punct'></</span><span class='tag'>code</span><span class='punct'>></span> function.<span class='punct'></</span><span class='tag'>p</span><span class='punct'>></span></pre>
|
|
680
|
-
|
|
681
|
-
<p>To include a literal backtick character within a code span, you can backslash escape it:</p>
|
|
682
|
-
|
|
683
|
-
<pre><code>`There is a literal backtick (\\`) here.`
|
|
518
|
+
<pre><code><p>Use the <code>printf()</code> function.</p>
|
|
684
519
|
</code></pre>
|
|
685
|
-
|
|
686
|
-
<p>Or, if you prefer, you can use multiple backticks as the opening and closing delimiters:</p>
|
|
687
|
-
|
|
520
|
+
<p>To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:</p>
|
|
688
521
|
<pre><code>``There is a literal backtick (`) here.``
|
|
689
522
|
</code></pre>
|
|
523
|
+
<p>which will produce this:</p>
|
|
524
|
+
<pre><code><p><code>There is a literal backtick (`) here.</code></p>
|
|
525
|
+
</code></pre>
|
|
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
|
+
<pre><code>A single backtick in a code span: `` ` ``
|
|
690
528
|
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
<
|
|
529
|
+
A backtick-delimited string in a code span: `` `foo` ``
|
|
530
|
+
</code></pre>
|
|
531
|
+
<p>will produce:</p>
|
|
532
|
+
<pre><code><p>A single backtick in a code span: <code>`</code></p>
|
|
694
533
|
|
|
534
|
+
<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
|
|
535
|
+
</code></pre>
|
|
695
536
|
<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>
|
|
696
|
-
|
|
697
537
|
<pre><code>Please don't use any `<blink>` tags.
|
|
698
538
|
</code></pre>
|
|
699
|
-
|
|
700
539
|
<p>into:</p>
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
540
|
+
<pre><code><p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
|
|
541
|
+
</code></pre>
|
|
704
542
|
<p>You can write this:</p>
|
|
705
|
-
|
|
706
543
|
<pre><code>`&#8212;` is the decimal-encoded equivalent of `&mdash;`.
|
|
707
544
|
</code></pre>
|
|
708
|
-
|
|
709
545
|
<p>to produce:</p>
|
|
546
|
+
<pre><code><p><code>&amp;#8212;</code> is the decimal-encoded
|
|
547
|
+
equivalent of <code>&amp;mdash;</code>.</p>
|
|
710
548
|
|
|
711
|
-
<pre class='xml'><span class='punct'><</span><span class='tag'>p</span><span class='punct'>><</span><span class='tag'>code</span><span class='punct'>></span><span class='entity'>&amp;#8212;</span><span class='punct'></</span><span class='tag'>code</span><span class='punct'>></span> is the decimal-encoded
|
|
712
|
-
equivalent of <span class='punct'><</span><span class='tag'>code</span><span class='punct'>></span><span class='entity'>&amp;mdash;</span><span class='punct'></</span><span class='tag'>code</span><span class='punct'>></span>.<span class='punct'></</span><span class='tag'>p</span><span class='punct'>></span></pre>
|
|
713
|
-
|
|
714
|
-
<h3 id='img'><span class='maruku_section_number'>3.4. </span>Images</h3>
|
|
715
549
|
|
|
550
|
+
</code></pre><h3 id='img'>Images</h3>
|
|
716
551
|
<p>Admittedly, it's fairly difficult to devise a "natural" syntax for placing images into a plain text document format.</p>
|
|
717
552
|
|
|
718
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>
|
|
719
554
|
|
|
720
555
|
<p>Inline image syntax looks like this:</p>
|
|
721
|
-
|
|
722
556
|
<pre><code>
|
|
723
557
|
|
|
724
558
|
|
|
725
559
|
</code></pre>
|
|
726
|
-
|
|
727
560
|
<p>That is:</p>
|
|
728
561
|
|
|
729
562
|
<ul>
|
|
@@ -735,56 +568,35 @@ equivalent of <span class='punct'><</span><span class='tag'>code</span><span
|
|
|
735
568
|
</ul>
|
|
736
569
|
|
|
737
570
|
<p>Reference-style image syntax looks like this:</p>
|
|
738
|
-
|
|
739
571
|
<pre><code>![Alt text][id]
|
|
740
572
|
</code></pre>
|
|
741
|
-
|
|
742
573
|
<p>Where "id" is the name of a defined image reference. Image references are defined using syntax identical to link references:</p>
|
|
743
|
-
|
|
744
574
|
<pre><code>[id]: url/to/image "Optional title attribute"
|
|
745
575
|
</code></pre>
|
|
746
|
-
|
|
747
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>
|
|
748
|
-
|
|
749
|
-
<hr />
|
|
750
|
-
|
|
751
|
-
<h2 id='misc'><span class='maruku_section_number'>4. </span>Miscellaneous</h2>
|
|
752
|
-
|
|
753
|
-
<h3 id='autolink'><span class='maruku_section_number'>4.1. </span>Automatic Links</h3>
|
|
754
|
-
|
|
577
|
+
<hr /><h2 id='misc'>Miscellaneous</h2><h3 id='autolink'>Automatic Links</h3>
|
|
755
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>
|
|
756
|
-
|
|
757
579
|
<pre><code><http://example.com/></code></pre>
|
|
758
|
-
|
|
759
580
|
<p>Markdown will turn this into:</p>
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
581
|
+
<pre><code><a href="http://example.com/">http://example.com/</a>
|
|
582
|
+
</code></pre>
|
|
763
583
|
<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>
|
|
764
|
-
|
|
765
584
|
<pre><code><address@example.com>
|
|
766
585
|
</code></pre>
|
|
767
|
-
|
|
768
586
|
<p>into something like this:</p>
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
587
|
+
<pre><code><a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
|
|
588
|
+
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
|
|
589
|
+
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
|
|
590
|
+
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
|
|
591
|
+
</code></pre>
|
|
775
592
|
<p>which will render in a browser as a clickable link to "address@example.com".</p>
|
|
776
593
|
|
|
777
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>
|
|
778
|
-
|
|
779
|
-
<h3 id='backslash'><span class='maruku_section_number'>4.2. </span>Backslash Escapes</h3>
|
|
780
|
-
|
|
595
|
+
<h3 id='backslash'>Backslash Escapes</h3>
|
|
781
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>
|
|
782
|
-
|
|
783
597
|
<pre><code>\*literal asterisks\*
|
|
784
598
|
</code></pre>
|
|
785
|
-
|
|
786
599
|
<p>Markdown provides backslash escapes for the following characters:</p>
|
|
787
|
-
|
|
788
600
|
<pre><code>\ backslash
|
|
789
601
|
` backtick
|
|
790
602
|
* asterisk
|
|
@@ -793,10 +605,7 @@ _ underscore
|
|
|
793
605
|
[] square brackets
|
|
794
606
|
() parentheses
|
|
795
607
|
# hash mark
|
|
608
|
+
+ plus sign
|
|
609
|
+
- minus sign (hyphen)
|
|
796
610
|
. dot
|
|
797
|
-
! exclamation mark</code></pre>
|
|
798
|
-
|
|
799
|
-
<div class='maruku_signature'>
|
|
800
|
-
<hr />
|
|
801
|
-
<span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown interpreter'>Maruku</a> at 00:21 on Wednesday, January 03rd, 2007.</span></div>
|
|
802
|
-
</body></html>
|
|
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 10:36 on Saturday, January 06th, 2007.</span></div></body></html>
|