tartan 0.1.1 → 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- data/History.txt +11 -0
- data/Manifest.txt +42 -0
- data/{README → README.txt} +12 -8
- data/Rakefile +78 -0
- data/lib/core_ext/array.rb +9 -10
- data/lib/core_ext/module.rb +2 -0
- data/lib/{symbolize.rb → core_ext/symbolize.rb} +0 -0
- data/lib/core_ext.rb +7 -0
- data/lib/{markdown.yml → tartan/markdown/markdown.yml} +67 -25
- data/lib/tartan/markdown/rules.rb +11 -0
- data/lib/tartan/markdown.rb +14 -0
- data/lib/tartan/table/rules.rb +11 -0
- data/lib/{table.yml → tartan/table/table.yml} +1 -1
- data/lib/tartan/test/base_rules.rb +9 -0
- data/lib/{test_base.yml → tartan/test/test_base.yml} +0 -0
- data/lib/{wiki-test.rb → tartan/test/wiki-test.rb} +15 -12
- data/lib/tartan/wiki_rule.rb +242 -0
- data/lib/tartan/wikilink/rules.rb +18 -0
- data/lib/{wikilink.yml → tartan/wikilink/wikilink.yml} +4 -2
- data/lib/tartan.rb +259 -270
- data/test/test-combo.rb +21 -14
- data/test/test-combo.yml +17 -0
- data/test/test-markdown-and-wikilink.rb +22 -0
- data/test/test-markdown-and-wikilink.yml +6 -0
- data/test/test-markdown.rb +4 -5
- data/test/test-markdown.yml +194 -1
- data/test/test-readme-example.rb +6 -5
- data/test/test-tables.rb +11 -7
- data/test/test-tartan.rb +8 -7
- data/test/test-wikilink.rb +13 -9
- data/test/test-wikilink.yml +3 -0
- metadata +47 -86
- data/lib/tartan_markdown.rb +0 -8
- data/lib/tartan_markdown_def.rb +0 -7
- data/lib/tartan_table_def.rb +0 -7
- data/lib/tartan_test_base_def.rb +0 -5
- data/lib/tartan_wikilink_def.rb +0 -14
- data/lib/wiki_rule.rb +0 -240
- data/test/MarkdownTest_1.0/Amps and angle encoding.html +0 -17
- data/test/MarkdownTest_1.0/Amps and angle encoding.text +0 -21
- data/test/MarkdownTest_1.0/Auto links.html +0 -18
- data/test/MarkdownTest_1.0/Auto links.text +0 -13
- data/test/MarkdownTest_1.0/Backslash codeescapes.html +0 -68
- data/test/MarkdownTest_1.0/Backslash codeescapes.text +0 -68
- data/test/MarkdownTest_1.0/Backslash simpleescapes.html +0 -33
- data/test/MarkdownTest_1.0/Backslash simpleescapes.text +0 -33
- data/test/MarkdownTest_1.0/Blockquotes with code blocks.html +0 -15
- data/test/MarkdownTest_1.0/Blockquotes with code blocks.text +0 -11
- data/test/MarkdownTest_1.0/Hard-wrapped paragraphs with list-like lines.html +0 -8
- data/test/MarkdownTest_1.0/Hard-wrapped paragraphs with list-like lines.text +0 -8
- data/test/MarkdownTest_1.0/Horizontal rules.html +0 -71
- data/test/MarkdownTest_1.0/Horizontal rules.text +0 -67
- data/test/MarkdownTest_1.0/Inline HTML (Advanced).html +0 -14
- data/test/MarkdownTest_1.0/Inline HTML (Advanced).text +0 -14
- data/test/MarkdownTest_1.0/Inline HTML (Simple).html +0 -72
- data/test/MarkdownTest_1.0/Inline HTML (Simple).text +0 -69
- data/test/MarkdownTest_1.0/Inline HTML comments.html +0 -13
- data/test/MarkdownTest_1.0/Inline HTML comments.text +0 -13
- data/test/MarkdownTest_1.0/Links, inline style.html +0 -9
- data/test/MarkdownTest_1.0/Links, inline style.text +0 -9
- data/test/MarkdownTest_1.0/Links, reference style.html +0 -18
- data/test/MarkdownTest_1.0/Links, reference style.text +0 -31
- data/test/MarkdownTest_1.0/Literal quotes in titles.html +0 -3
- data/test/MarkdownTest_1.0/Literal quotes in titles.text +0 -7
- data/test/MarkdownTest_1.0/Markdown Documentation - Basics.html +0 -314
- data/test/MarkdownTest_1.0/Markdown Documentation - Basics.out +0 -316
- data/test/MarkdownTest_1.0/Markdown Documentation - Basics.text +0 -306
- data/test/MarkdownTest_1.0/Markdown Documentation - Syntax.html +0 -942
- data/test/MarkdownTest_1.0/Markdown Documentation - Syntax.out +0 -947
- data/test/MarkdownTest_1.0/Markdown Documentation - Syntax.text +0 -888
- data/test/MarkdownTest_1.0/Nested blockquotes.html +0 -9
- data/test/MarkdownTest_1.0/Nested blockquotes.text +0 -5
- data/test/MarkdownTest_1.0/Ordered and unordered lists.html +0 -137
- data/test/MarkdownTest_1.0/Ordered and unordered lists.text +0 -122
- data/test/MarkdownTest_1.0/Strong and em together.html +0 -7
- data/test/MarkdownTest_1.0/Strong and em together.text +0 -7
- data/test/MarkdownTest_1.0/Tabs.html +0 -25
- data/test/MarkdownTest_1.0/Tabs.text +0 -21
- data/test/MarkdownTest_1.0/Tidyness.html +0 -8
- data/test/MarkdownTest_1.0/Tidyness.text +0 -5
- data/test/MarkdownTest_1.0/run-markdown.rb +0 -56
- data/test/MarkdownTest_1.0/test-fireball-markdown.rb +0 -177
- data/test/MarkdownTest_1.0/testdiff.rb +0 -42
- data/test/harder/test-markdown-harder.rb +0 -11
- data/test/harder/test-markdown-harder.yml +0 -111
- data/test/redcloth/redcloth-markdown-tests.rb +0 -29
- data/test/redcloth/redcloth-markdown-tests.yml +0 -218
- data/test/test-tartan-markdown.rb +0 -11
|
@@ -1,942 +0,0 @@
|
|
|
1
|
-
<h1>Markdown: Syntax</h1>
|
|
2
|
-
|
|
3
|
-
<ul id="ProjectSubmenu">
|
|
4
|
-
<li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
|
|
5
|
-
<li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
|
|
6
|
-
<li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
|
|
7
|
-
<li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
|
|
8
|
-
<li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
|
|
9
|
-
</ul>
|
|
10
|
-
|
|
11
|
-
<ul>
|
|
12
|
-
<li><a href="#overview">Overview</a>
|
|
13
|
-
<ul>
|
|
14
|
-
<li><a href="#philosophy">Philosophy</a></li>
|
|
15
|
-
<li><a href="#html">Inline HTML</a></li>
|
|
16
|
-
<li><a href="#autoescape">Automatic Escaping for Special Characters</a></li>
|
|
17
|
-
</ul></li>
|
|
18
|
-
<li><a href="#block">Block Elements</a>
|
|
19
|
-
<ul>
|
|
20
|
-
<li><a href="#p">Paragraphs and Line Breaks</a></li>
|
|
21
|
-
<li><a href="#header">Headers</a></li>
|
|
22
|
-
<li><a href="#blockquote">Blockquotes</a></li>
|
|
23
|
-
<li><a href="#list">Lists</a></li>
|
|
24
|
-
<li><a href="#precode">Code Blocks</a></li>
|
|
25
|
-
<li><a href="#hr">Horizontal Rules</a></li>
|
|
26
|
-
</ul></li>
|
|
27
|
-
<li><a href="#span">Span Elements</a>
|
|
28
|
-
<ul>
|
|
29
|
-
<li><a href="#link">Links</a></li>
|
|
30
|
-
<li><a href="#em">Emphasis</a></li>
|
|
31
|
-
<li><a href="#code">Code</a></li>
|
|
32
|
-
<li><a href="#img">Images</a></li>
|
|
33
|
-
</ul></li>
|
|
34
|
-
<li><a href="#misc">Miscellaneous</a>
|
|
35
|
-
<ul>
|
|
36
|
-
<li><a href="#backslash">Backslash Escapes</a></li>
|
|
37
|
-
<li><a href="#autolink">Automatic Links</a></li>
|
|
38
|
-
</ul></li>
|
|
39
|
-
</ul>
|
|
40
|
-
|
|
41
|
-
<p><strong>Note:</strong> This document is itself written using Markdown; you
|
|
42
|
-
can <a href="/projects/markdown/syntax.text">see the source for it by adding '.text' to the URL</a>.</p>
|
|
43
|
-
|
|
44
|
-
<hr />
|
|
45
|
-
|
|
46
|
-
<h2 id="overview">Overview</h2>
|
|
47
|
-
|
|
48
|
-
<h3 id="philosophy">Philosophy</h3>
|
|
49
|
-
|
|
50
|
-
<p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.</p>
|
|
51
|
-
|
|
52
|
-
<p>Readability, however, is emphasized above all else. A Markdown-formatted
|
|
53
|
-
document should be publishable as-is, as plain text, without looking
|
|
54
|
-
like it's been marked up with tags or formatting instructions. While
|
|
55
|
-
Markdown's syntax has been influenced by several existing text-to-HTML
|
|
56
|
-
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>,
|
|
57
|
-
<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
|
|
58
|
-
inspiration for Markdown's syntax is the format of plain text email.</p>
|
|
59
|
-
|
|
60
|
-
<p>To this end, Markdown's syntax is comprised entirely of punctuation
|
|
61
|
-
characters, which punctuation characters have been carefully chosen so
|
|
62
|
-
as to look like what they mean. E.g., asterisks around a word actually
|
|
63
|
-
look like *emphasis*. Markdown lists look like, well, lists. Even
|
|
64
|
-
blockquotes look like quoted passages of text, assuming you've ever
|
|
65
|
-
used email.</p>
|
|
66
|
-
|
|
67
|
-
<h3 id="html">Inline HTML</h3>
|
|
68
|
-
|
|
69
|
-
<p>Markdown's syntax is intended for one purpose: to be used as a
|
|
70
|
-
format for <em>writing</em> for the web.</p>
|
|
71
|
-
|
|
72
|
-
<p>Markdown is not a replacement for HTML, or even close to it. Its
|
|
73
|
-
syntax is very small, corresponding only to a very small subset of
|
|
74
|
-
HTML tags. The idea is <em>not</em> to create a syntax that makes it easier
|
|
75
|
-
to insert HTML tags. In my opinion, HTML tags are already easy to
|
|
76
|
-
insert. The idea for Markdown is to make it easy to read, write, and
|
|
77
|
-
edit prose. HTML is a <em>publishing</em> format; Markdown is a <em>writing</em>
|
|
78
|
-
format. Thus, Markdown's formatting syntax only addresses issues that
|
|
79
|
-
can be conveyed in plain text.</p>
|
|
80
|
-
|
|
81
|
-
<p>For any markup that is not covered by Markdown's syntax, you simply
|
|
82
|
-
use HTML itself. There's no need to preface it or delimit it to
|
|
83
|
-
indicate that you're switching from Markdown to HTML; you just use
|
|
84
|
-
the tags.</p>
|
|
85
|
-
|
|
86
|
-
<p>The only restrictions are that block-level HTML elements -- e.g. <code><div></code>,
|
|
87
|
-
<code><table></code>, <code><pre></code>, <code><p></code>, etc. -- must be separated from surrounding
|
|
88
|
-
content by blank lines, and the start and end tags of the block should
|
|
89
|
-
not be indented with tabs or spaces. Markdown is smart enough not
|
|
90
|
-
to add extra (unwanted) <code><p></code> tags around HTML block-level tags.</p>
|
|
91
|
-
|
|
92
|
-
<p>For example, to add an HTML table to a Markdown article:</p>
|
|
93
|
-
|
|
94
|
-
<pre><code>This is a regular paragraph.
|
|
95
|
-
|
|
96
|
-
<table>
|
|
97
|
-
<tr>
|
|
98
|
-
<td>Foo</td>
|
|
99
|
-
</tr>
|
|
100
|
-
</table>
|
|
101
|
-
|
|
102
|
-
This is another regular paragraph.
|
|
103
|
-
</code></pre>
|
|
104
|
-
|
|
105
|
-
<p>Note that Markdown formatting syntax is not processed within block-level
|
|
106
|
-
HTML tags. E.g., you can't use Markdown-style <code>*emphasis*</code> inside an
|
|
107
|
-
HTML block.</p>
|
|
108
|
-
|
|
109
|
-
<p>Span-level HTML tags -- e.g. <code><span></code>, <code><cite></code>, or <code><del></code> -- can be
|
|
110
|
-
used anywhere in a Markdown paragraph, list item, or header. If you
|
|
111
|
-
want, you can even use HTML tags instead of Markdown formatting; e.g. if
|
|
112
|
-
you'd prefer to use HTML <code><a></code> or <code><img></code> tags instead of Markdown's
|
|
113
|
-
link or image syntax, go right ahead.</p>
|
|
114
|
-
|
|
115
|
-
<p>Unlike block-level HTML tags, Markdown syntax <em>is</em> processed within
|
|
116
|
-
span-level tags.</p>
|
|
117
|
-
|
|
118
|
-
<h3 id="autoescape">Automatic Escaping for Special Characters</h3>
|
|
119
|
-
|
|
120
|
-
<p>In HTML, there are two characters that demand special treatment: <code><</code>
|
|
121
|
-
and <code>&</code>. Left angle brackets are used to start tags; ampersands are
|
|
122
|
-
used to denote HTML entities. If you want to use them as literal
|
|
123
|
-
characters, you must escape them as entities, e.g. <code>&lt;</code>, and
|
|
124
|
-
<code>&amp;</code>.</p>
|
|
125
|
-
|
|
126
|
-
<p>Ampersands in particular are bedeviling for web writers. If you want to
|
|
127
|
-
write about 'AT&T', you need to write '<code>AT&amp;T</code>'. You even need to
|
|
128
|
-
escape ampersands within URLs. Thus, if you want to link to:</p>
|
|
129
|
-
|
|
130
|
-
<pre><code>http://images.google.com/images?num=30&q=larry+bird
|
|
131
|
-
</code></pre>
|
|
132
|
-
|
|
133
|
-
<p>you need to encode the URL as:</p>
|
|
134
|
-
|
|
135
|
-
<pre><code>http://images.google.com/images?num=30&amp;q=larry+bird
|
|
136
|
-
</code></pre>
|
|
137
|
-
|
|
138
|
-
<p>in your anchor tag <code>href</code> attribute. Needless to say, this is easy to
|
|
139
|
-
forget, and is probably the single most common source of HTML validation
|
|
140
|
-
errors in otherwise well-marked-up web sites.</p>
|
|
141
|
-
|
|
142
|
-
<p>Markdown allows you to use these characters naturally, taking care of
|
|
143
|
-
all the necessary escaping for you. If you use an ampersand as part of
|
|
144
|
-
an HTML entity, it remains unchanged; otherwise it will be translated
|
|
145
|
-
into <code>&amp;</code>.</p>
|
|
146
|
-
|
|
147
|
-
<p>So, if you want to include a copyright symbol in your article, you can write:</p>
|
|
148
|
-
|
|
149
|
-
<pre><code>&copy;
|
|
150
|
-
</code></pre>
|
|
151
|
-
|
|
152
|
-
<p>and Markdown will leave it alone. But if you write:</p>
|
|
153
|
-
|
|
154
|
-
<pre><code>AT&T
|
|
155
|
-
</code></pre>
|
|
156
|
-
|
|
157
|
-
<p>Markdown will translate it to:</p>
|
|
158
|
-
|
|
159
|
-
<pre><code>AT&amp;T
|
|
160
|
-
</code></pre>
|
|
161
|
-
|
|
162
|
-
<p>Similarly, because Markdown supports <a href="#html">inline HTML</a>, if you use
|
|
163
|
-
angle brackets as delimiters for HTML tags, Markdown will treat them as
|
|
164
|
-
such. But if you write:</p>
|
|
165
|
-
|
|
166
|
-
<pre><code>4 < 5
|
|
167
|
-
</code></pre>
|
|
168
|
-
|
|
169
|
-
<p>Markdown will translate it to:</p>
|
|
170
|
-
|
|
171
|
-
<pre><code>4 &lt; 5
|
|
172
|
-
</code></pre>
|
|
173
|
-
|
|
174
|
-
<p>However, inside Markdown code spans and blocks, angle brackets and
|
|
175
|
-
ampersands are <em>always</em> encoded automatically. This makes it easy to use
|
|
176
|
-
Markdown to write about HTML code. (As opposed to raw HTML, which is a
|
|
177
|
-
terrible format for writing about HTML syntax, because every single <code><</code>
|
|
178
|
-
and <code>&</code> in your example code needs to be escaped.)</p>
|
|
179
|
-
|
|
180
|
-
<hr />
|
|
181
|
-
|
|
182
|
-
<h2 id="block">Block Elements</h2>
|
|
183
|
-
|
|
184
|
-
<h3 id="p">Paragraphs and Line Breaks</h3>
|
|
185
|
-
|
|
186
|
-
<p>A paragraph is simply one or more consecutive lines of text, separated
|
|
187
|
-
by one or more blank lines. (A blank line is any line that looks like a
|
|
188
|
-
blank line -- a line containing nothing but spaces or tabs is considered
|
|
189
|
-
blank.) Normal paragraphs should not be intended with spaces or tabs.</p>
|
|
190
|
-
|
|
191
|
-
<p>The implication of the "one or more consecutive lines of text" rule is
|
|
192
|
-
that Markdown supports "hard-wrapped" text paragraphs. This differs
|
|
193
|
-
significantly from most other text-to-HTML formatters (including Movable
|
|
194
|
-
Type's "Convert Line Breaks" option) which translate every line break
|
|
195
|
-
character in a paragraph into a <code><br /></code> tag.</p>
|
|
196
|
-
|
|
197
|
-
<p>When you <em>do</em> want to insert a <code><br /></code> break tag using Markdown, you
|
|
198
|
-
end a line with two or more spaces, then type return.</p>
|
|
199
|
-
|
|
200
|
-
<p>Yes, this takes a tad more effort to create a <code><br /></code>, but a simplistic
|
|
201
|
-
"every line break is a <code><br /></code>" rule wouldn't work for Markdown.
|
|
202
|
-
Markdown's email-style <a href="#blockquote">blockquoting</a> and multi-paragraph <a href="#list">list items</a>
|
|
203
|
-
work best -- and look better -- when you format them with hard breaks.</p>
|
|
204
|
-
|
|
205
|
-
<h3 id="header">Headers</h3>
|
|
206
|
-
|
|
207
|
-
<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>
|
|
208
|
-
|
|
209
|
-
<p>Setext-style headers are "underlined" using equal signs (for first-level
|
|
210
|
-
headers) and dashes (for second-level headers). For example:</p>
|
|
211
|
-
|
|
212
|
-
<pre><code>This is an H1
|
|
213
|
-
=============
|
|
214
|
-
|
|
215
|
-
This is an H2
|
|
216
|
-
-------------
|
|
217
|
-
</code></pre>
|
|
218
|
-
|
|
219
|
-
<p>Any number of underlining <code>=</code>'s or <code>-</code>'s will work.</p>
|
|
220
|
-
|
|
221
|
-
<p>Atx-style headers use 1-6 hash characters at the start of the line,
|
|
222
|
-
corresponding to header levels 1-6. For example:</p>
|
|
223
|
-
|
|
224
|
-
<pre><code># This is an H1
|
|
225
|
-
|
|
226
|
-
## This is an H2
|
|
227
|
-
|
|
228
|
-
###### This is an H6
|
|
229
|
-
</code></pre>
|
|
230
|
-
|
|
231
|
-
<p>Optionally, you may "close" atx-style headers. This is purely
|
|
232
|
-
cosmetic -- you can use this if you think it looks better. The
|
|
233
|
-
closing hashes don't even need to match the number of hashes
|
|
234
|
-
used to open the header. (The number of opening hashes
|
|
235
|
-
determines the header level.) :</p>
|
|
236
|
-
|
|
237
|
-
<pre><code># This is an H1 #
|
|
238
|
-
|
|
239
|
-
## This is an H2 ##
|
|
240
|
-
|
|
241
|
-
### This is an H3 ######
|
|
242
|
-
</code></pre>
|
|
243
|
-
|
|
244
|
-
<h3 id="blockquote">Blockquotes</h3>
|
|
245
|
-
|
|
246
|
-
<p>Markdown uses email-style <code>></code> characters for blockquoting. If you're
|
|
247
|
-
familiar with quoting passages of text in an email message, then you
|
|
248
|
-
know how to create a blockquote in Markdown. It looks best if you hard
|
|
249
|
-
wrap the text and put a <code>></code> before every line:</p>
|
|
250
|
-
|
|
251
|
-
<pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
|
252
|
-
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
|
253
|
-
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
|
254
|
-
>
|
|
255
|
-
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
|
256
|
-
> id sem consectetuer libero luctus adipiscing.
|
|
257
|
-
</code></pre>
|
|
258
|
-
|
|
259
|
-
<p>Markdown allows you to be lazy and only put the <code>></code> before the first
|
|
260
|
-
line of a hard-wrapped paragraph:</p>
|
|
261
|
-
|
|
262
|
-
<pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
|
263
|
-
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
|
264
|
-
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
|
265
|
-
|
|
266
|
-
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
|
267
|
-
id sem consectetuer libero luctus adipiscing.
|
|
268
|
-
</code></pre>
|
|
269
|
-
|
|
270
|
-
<p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
|
|
271
|
-
adding additional levels of <code>></code>:</p>
|
|
272
|
-
|
|
273
|
-
<pre><code>> This is the first level of quoting.
|
|
274
|
-
>
|
|
275
|
-
> > This is nested blockquote.
|
|
276
|
-
>
|
|
277
|
-
> Back to the first level.
|
|
278
|
-
</code></pre>
|
|
279
|
-
|
|
280
|
-
<p>Blockquotes can contain other Markdown elements, including headers, lists,
|
|
281
|
-
and code blocks:</p>
|
|
282
|
-
|
|
283
|
-
<pre><code>> ## This is a header.
|
|
284
|
-
>
|
|
285
|
-
> 1. This is the first list item.
|
|
286
|
-
> 2. This is the second list item.
|
|
287
|
-
>
|
|
288
|
-
> Here's some example code:
|
|
289
|
-
>
|
|
290
|
-
> return shell_exec("echo $input | $markdown_script");
|
|
291
|
-
</code></pre>
|
|
292
|
-
|
|
293
|
-
<p>Any decent text editor should make email-style quoting easy. For
|
|
294
|
-
example, with BBEdit, you can make a selection and choose Increase
|
|
295
|
-
Quote Level from the Text menu.</p>
|
|
296
|
-
|
|
297
|
-
<h3 id="list">Lists</h3>
|
|
298
|
-
|
|
299
|
-
<p>Markdown supports ordered (numbered) and unordered (bulleted) lists.</p>
|
|
300
|
-
|
|
301
|
-
<p>Unordered lists use asterisks, pluses, and hyphens -- interchangably
|
|
302
|
-
-- as list markers:</p>
|
|
303
|
-
|
|
304
|
-
<pre><code>* Red
|
|
305
|
-
* Green
|
|
306
|
-
* Blue
|
|
307
|
-
</code></pre>
|
|
308
|
-
|
|
309
|
-
<p>is equivalent to:</p>
|
|
310
|
-
|
|
311
|
-
<pre><code>+ Red
|
|
312
|
-
+ Green
|
|
313
|
-
+ Blue
|
|
314
|
-
</code></pre>
|
|
315
|
-
|
|
316
|
-
<p>and:</p>
|
|
317
|
-
|
|
318
|
-
<pre><code>- Red
|
|
319
|
-
- Green
|
|
320
|
-
- Blue
|
|
321
|
-
</code></pre>
|
|
322
|
-
|
|
323
|
-
<p>Ordered lists use numbers followed by periods:</p>
|
|
324
|
-
|
|
325
|
-
<pre><code>1. Bird
|
|
326
|
-
2. McHale
|
|
327
|
-
3. Parish
|
|
328
|
-
</code></pre>
|
|
329
|
-
|
|
330
|
-
<p>It's important to note that the actual numbers you use to mark the
|
|
331
|
-
list have no effect on the HTML output Markdown produces. The HTML
|
|
332
|
-
Markdown produces from the above list is:</p>
|
|
333
|
-
|
|
334
|
-
<pre><code><ol>
|
|
335
|
-
<li>Bird</li>
|
|
336
|
-
<li>McHale</li>
|
|
337
|
-
<li>Parish</li>
|
|
338
|
-
</ol>
|
|
339
|
-
</code></pre>
|
|
340
|
-
|
|
341
|
-
<p>If you instead wrote the list in Markdown like this:</p>
|
|
342
|
-
|
|
343
|
-
<pre><code>1. Bird
|
|
344
|
-
1. McHale
|
|
345
|
-
1. Parish
|
|
346
|
-
</code></pre>
|
|
347
|
-
|
|
348
|
-
<p>or even:</p>
|
|
349
|
-
|
|
350
|
-
<pre><code>3. Bird
|
|
351
|
-
1. McHale
|
|
352
|
-
8. Parish
|
|
353
|
-
</code></pre>
|
|
354
|
-
|
|
355
|
-
<p>you'd get the exact same HTML output. The point is, if you want to,
|
|
356
|
-
you can use ordinal numbers in your ordered Markdown lists, so that
|
|
357
|
-
the numbers in your source match the numbers in your published HTML.
|
|
358
|
-
But if you want to be lazy, you don't have to.</p>
|
|
359
|
-
|
|
360
|
-
<p>If you do use lazy list numbering, however, you should still start the
|
|
361
|
-
list with the number 1. At some point in the future, Markdown may support
|
|
362
|
-
starting ordered lists at an arbitrary number.</p>
|
|
363
|
-
|
|
364
|
-
<p>List markers typically start at the left margin, but may be indented by
|
|
365
|
-
up to three spaces. List markers must be followed by one or more spaces
|
|
366
|
-
or a tab.</p>
|
|
367
|
-
|
|
368
|
-
<p>To make lists look nice, you can wrap items with hanging indents:</p>
|
|
369
|
-
|
|
370
|
-
<pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
371
|
-
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
|
372
|
-
viverra nec, fringilla in, laoreet vitae, risus.
|
|
373
|
-
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
|
374
|
-
Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
375
|
-
</code></pre>
|
|
376
|
-
|
|
377
|
-
<p>But if you want to be lazy, you don't have to:</p>
|
|
378
|
-
|
|
379
|
-
<pre><code>* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
|
380
|
-
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
|
381
|
-
viverra nec, fringilla in, laoreet vitae, risus.
|
|
382
|
-
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
|
383
|
-
Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
384
|
-
</code></pre>
|
|
385
|
-
|
|
386
|
-
<p>If list items are separated by blank lines, Markdown will wrap the
|
|
387
|
-
items in <code><p></code> tags in the HTML output. For example, this input:</p>
|
|
388
|
-
|
|
389
|
-
<pre><code>* Bird
|
|
390
|
-
* Magic
|
|
391
|
-
</code></pre>
|
|
392
|
-
|
|
393
|
-
<p>will turn into:</p>
|
|
394
|
-
|
|
395
|
-
<pre><code><ul>
|
|
396
|
-
<li>Bird</li>
|
|
397
|
-
<li>Magic</li>
|
|
398
|
-
</ul>
|
|
399
|
-
</code></pre>
|
|
400
|
-
|
|
401
|
-
<p>But this:</p>
|
|
402
|
-
|
|
403
|
-
<pre><code>* Bird
|
|
404
|
-
|
|
405
|
-
* Magic
|
|
406
|
-
</code></pre>
|
|
407
|
-
|
|
408
|
-
<p>will turn into:</p>
|
|
409
|
-
|
|
410
|
-
<pre><code><ul>
|
|
411
|
-
<li><p>Bird</p></li>
|
|
412
|
-
<li><p>Magic</p></li>
|
|
413
|
-
</ul>
|
|
414
|
-
</code></pre>
|
|
415
|
-
|
|
416
|
-
<p>List items may consist of multiple paragraphs. Each subsequent
|
|
417
|
-
paragraph in a list item must be intended by either 4 spaces
|
|
418
|
-
or one tab:</p>
|
|
419
|
-
|
|
420
|
-
<pre><code>1. This is a list item with two paragraphs. Lorem ipsum dolor
|
|
421
|
-
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
|
|
422
|
-
mi posuere lectus.
|
|
423
|
-
|
|
424
|
-
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
|
|
425
|
-
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
|
|
426
|
-
sit amet velit.
|
|
427
|
-
|
|
428
|
-
2. Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
429
|
-
</code></pre>
|
|
430
|
-
|
|
431
|
-
<p>It looks nice if you indent every line of the subsequent
|
|
432
|
-
paragraphs, but here again, Markdown will allow you to be
|
|
433
|
-
lazy:</p>
|
|
434
|
-
|
|
435
|
-
<pre><code>* This is a list item with two paragraphs.
|
|
436
|
-
|
|
437
|
-
This is the second paragraph in the list item. You're
|
|
438
|
-
only required to indent the first line. Lorem ipsum dolor
|
|
439
|
-
sit amet, consectetuer adipiscing elit.
|
|
440
|
-
|
|
441
|
-
* Another item in the same list.
|
|
442
|
-
</code></pre>
|
|
443
|
-
|
|
444
|
-
<p>To put a blockquote within a list item, the blockquote's <code>></code>
|
|
445
|
-
delimiters need to be indented:</p>
|
|
446
|
-
|
|
447
|
-
<pre><code>* A list item with a blockquote:
|
|
448
|
-
|
|
449
|
-
> This is a blockquote
|
|
450
|
-
> inside a list item.
|
|
451
|
-
</code></pre>
|
|
452
|
-
|
|
453
|
-
<p>To put a code block within a list item, the code block needs
|
|
454
|
-
to be indented <em>twice</em> -- 8 spaces or two tabs:</p>
|
|
455
|
-
|
|
456
|
-
<pre><code>* A list item with a code block:
|
|
457
|
-
|
|
458
|
-
<code goes here>
|
|
459
|
-
</code></pre>
|
|
460
|
-
|
|
461
|
-
<p>It's worth noting that it's possible to trigger an ordered list by
|
|
462
|
-
accident, by writing something like this:</p>
|
|
463
|
-
|
|
464
|
-
<pre><code>1986. What a great season.
|
|
465
|
-
</code></pre>
|
|
466
|
-
|
|
467
|
-
<p>In other words, a <em>number-period-space</em> sequence at the beginning of a
|
|
468
|
-
line. To avoid this, you can backslash-escape the period:</p>
|
|
469
|
-
|
|
470
|
-
<pre><code>1986\. What a great season.
|
|
471
|
-
</code></pre>
|
|
472
|
-
|
|
473
|
-
<h3 id="precode">Code Blocks</h3>
|
|
474
|
-
|
|
475
|
-
<p>Pre-formatted code blocks are used for writing about programming or
|
|
476
|
-
markup source code. Rather than forming normal paragraphs, the lines
|
|
477
|
-
of a code block are interpreted literally. Markdown wraps a code block
|
|
478
|
-
in both <code><pre></code> and <code><code></code> tags.</p>
|
|
479
|
-
|
|
480
|
-
<p>To produce a code block in Markdown, simply indent every line of the
|
|
481
|
-
block by at least 4 spaces or 1 tab. For example, given this input:</p>
|
|
482
|
-
|
|
483
|
-
<pre><code>This is a normal paragraph:
|
|
484
|
-
|
|
485
|
-
This is a code block.
|
|
486
|
-
</code></pre>
|
|
487
|
-
|
|
488
|
-
<p>Markdown will generate:</p>
|
|
489
|
-
|
|
490
|
-
<pre><code><p>This is a normal paragraph:</p>
|
|
491
|
-
|
|
492
|
-
<pre><code>This is a code block.
|
|
493
|
-
</code></pre>
|
|
494
|
-
</code></pre>
|
|
495
|
-
|
|
496
|
-
<p>One level of indentation -- 4 spaces or 1 tab -- is removed from each
|
|
497
|
-
line of the code block. For example, this:</p>
|
|
498
|
-
|
|
499
|
-
<pre><code>Here is an example of AppleScript:
|
|
500
|
-
|
|
501
|
-
tell application "Foo"
|
|
502
|
-
beep
|
|
503
|
-
end tell
|
|
504
|
-
</code></pre>
|
|
505
|
-
|
|
506
|
-
<p>will turn into:</p>
|
|
507
|
-
|
|
508
|
-
<pre><code><p>Here is an example of AppleScript:</p>
|
|
509
|
-
|
|
510
|
-
<pre><code>tell application "Foo"
|
|
511
|
-
beep
|
|
512
|
-
end tell
|
|
513
|
-
</code></pre>
|
|
514
|
-
</code></pre>
|
|
515
|
-
|
|
516
|
-
<p>A code block continues until it reaches a line that is not indented
|
|
517
|
-
(or the end of the article).</p>
|
|
518
|
-
|
|
519
|
-
<p>Within a code block, ampersands (<code>&</code>) and angle brackets (<code><</code> and <code>></code>)
|
|
520
|
-
are automatically converted into HTML entities. This makes it very
|
|
521
|
-
easy to include example HTML source code using Markdown -- just paste
|
|
522
|
-
it and indent it, and Markdown will handle the hassle of encoding the
|
|
523
|
-
ampersands and angle brackets. For example, this:</p>
|
|
524
|
-
|
|
525
|
-
<pre><code> <div class="footer">
|
|
526
|
-
&copy; 2004 Foo Corporation
|
|
527
|
-
</div>
|
|
528
|
-
</code></pre>
|
|
529
|
-
|
|
530
|
-
<p>will turn into:</p>
|
|
531
|
-
|
|
532
|
-
<pre><code><pre><code>&lt;div class="footer"&gt;
|
|
533
|
-
&amp;copy; 2004 Foo Corporation
|
|
534
|
-
&lt;/div&gt;
|
|
535
|
-
</code></pre>
|
|
536
|
-
</code></pre>
|
|
537
|
-
|
|
538
|
-
<p>Regular Markdown syntax is not processed within code blocks. E.g.,
|
|
539
|
-
asterisks are just literal asterisks within a code block. This means
|
|
540
|
-
it's also easy to use Markdown to write about Markdown's own syntax.</p>
|
|
541
|
-
|
|
542
|
-
<h3 id="hr">Horizontal Rules</h3>
|
|
543
|
-
|
|
544
|
-
<p>You can produce a horizontal rule tag (<code><hr /></code>) by placing three or
|
|
545
|
-
more hyphens, asterisks, or underscores on a line by themselves. If you
|
|
546
|
-
wish, you may use spaces between the hyphens or asterisks. Each of the
|
|
547
|
-
following lines will produce a horizontal rule:</p>
|
|
548
|
-
|
|
549
|
-
<pre><code>* * *
|
|
550
|
-
|
|
551
|
-
***
|
|
552
|
-
|
|
553
|
-
*****
|
|
554
|
-
|
|
555
|
-
- - -
|
|
556
|
-
|
|
557
|
-
---------------------------------------
|
|
558
|
-
|
|
559
|
-
_ _ _
|
|
560
|
-
</code></pre>
|
|
561
|
-
|
|
562
|
-
<hr />
|
|
563
|
-
|
|
564
|
-
<h2 id="span">Span Elements</h2>
|
|
565
|
-
|
|
566
|
-
<h3 id="link">Links</h3>
|
|
567
|
-
|
|
568
|
-
<p>Markdown supports two style of links: <em>inline</em> and <em>reference</em>.</p>
|
|
569
|
-
|
|
570
|
-
<p>In both styles, the link text is delimited by [square brackets].</p>
|
|
571
|
-
|
|
572
|
-
<p>To create an inline link, use a set of regular parentheses immediately
|
|
573
|
-
after the link text's closing square bracket. Inside the parentheses,
|
|
574
|
-
put the URL where you want the link to point, along with an <em>optional</em>
|
|
575
|
-
title for the link, surrounded in quotes. For example:</p>
|
|
576
|
-
|
|
577
|
-
<pre><code>This is [an example](http://example.com/ "Title") inline link.
|
|
578
|
-
|
|
579
|
-
[This link](http://example.net/) has no title attribute.
|
|
580
|
-
</code></pre>
|
|
581
|
-
|
|
582
|
-
<p>Will produce:</p>
|
|
583
|
-
|
|
584
|
-
<pre><code><p>This is <a href="http://example.com/" title="Title">
|
|
585
|
-
an example</a> inline link.</p>
|
|
586
|
-
|
|
587
|
-
<p><a href="http://example.net/">This link</a> has no
|
|
588
|
-
title attribute.</p>
|
|
589
|
-
</code></pre>
|
|
590
|
-
|
|
591
|
-
<p>If you're referring to a local resource on the same server, you can
|
|
592
|
-
use relative paths:</p>
|
|
593
|
-
|
|
594
|
-
<pre><code>See my [About](/about/) page for details.
|
|
595
|
-
</code></pre>
|
|
596
|
-
|
|
597
|
-
<p>Reference-style links use a second set of square brackets, inside
|
|
598
|
-
which you place a label of your choosing to identify the link:</p>
|
|
599
|
-
|
|
600
|
-
<pre><code>This is [an example][id] reference-style link.
|
|
601
|
-
</code></pre>
|
|
602
|
-
|
|
603
|
-
<p>You can optionally use a space to separate the sets of brackets:</p>
|
|
604
|
-
|
|
605
|
-
<pre><code>This is [an example] [id] reference-style link.
|
|
606
|
-
</code></pre>
|
|
607
|
-
|
|
608
|
-
<p>Then, anywhere in the document, you define your link label like this,
|
|
609
|
-
on a line by itself:</p>
|
|
610
|
-
|
|
611
|
-
<pre><code>[id]: http://example.com/ "Optional Title Here"
|
|
612
|
-
</code></pre>
|
|
613
|
-
|
|
614
|
-
<p>That is:</p>
|
|
615
|
-
|
|
616
|
-
<ul>
|
|
617
|
-
<li>Square brackets containing the link identifier (optionally
|
|
618
|
-
indented from the left margin using up to three spaces);</li>
|
|
619
|
-
<li>followed by a colon;</li>
|
|
620
|
-
<li>followed by one or more spaces (or tabs);</li>
|
|
621
|
-
<li>followed by the URL for the link;</li>
|
|
622
|
-
<li>optionally followed by a title attribute for the link, enclosed
|
|
623
|
-
in double or single quotes.</li>
|
|
624
|
-
</ul>
|
|
625
|
-
|
|
626
|
-
<p>The link URL may, optionally, be surrounded by angle brackets:</p>
|
|
627
|
-
|
|
628
|
-
<pre><code>[id]: <http://example.com/> "Optional Title Here"
|
|
629
|
-
</code></pre>
|
|
630
|
-
|
|
631
|
-
<p>You can put the title attribute on the next line and use extra spaces
|
|
632
|
-
or tabs for padding, which tends to look better with longer URLs:</p>
|
|
633
|
-
|
|
634
|
-
<pre><code>[id]: http://example.com/longish/path/to/resource/here
|
|
635
|
-
"Optional Title Here"
|
|
636
|
-
</code></pre>
|
|
637
|
-
|
|
638
|
-
<p>Link definitions are only used for creating links during Markdown
|
|
639
|
-
processing, and are stripped from your document in the HTML output.</p>
|
|
640
|
-
|
|
641
|
-
<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>
|
|
642
|
-
|
|
643
|
-
<pre><code>[link text][a]
|
|
644
|
-
[link text][A]
|
|
645
|
-
</code></pre>
|
|
646
|
-
|
|
647
|
-
<p>are equivalent.</p>
|
|
648
|
-
|
|
649
|
-
<p>The <em>implicit link name</em> shortcut allows you to omit the name of the
|
|
650
|
-
link, in which case the link text itself is used as the name.
|
|
651
|
-
Just use an empty set of square brackets -- e.g., to link the word
|
|
652
|
-
"Google" to the google.com web site, you could simply write:</p>
|
|
653
|
-
|
|
654
|
-
<pre><code>[Google][]
|
|
655
|
-
</code></pre>
|
|
656
|
-
|
|
657
|
-
<p>And then define the link:</p>
|
|
658
|
-
|
|
659
|
-
<pre><code>[Google]: http://google.com/
|
|
660
|
-
</code></pre>
|
|
661
|
-
|
|
662
|
-
<p>Because link names may contain spaces, this shortcut even works for
|
|
663
|
-
multiple words in the link text:</p>
|
|
664
|
-
|
|
665
|
-
<pre><code>Visit [Daring Fireball][] for more information.
|
|
666
|
-
</code></pre>
|
|
667
|
-
|
|
668
|
-
<p>And then define the link:</p>
|
|
669
|
-
|
|
670
|
-
<pre><code>[Daring Fireball]: http://daringfireball.net/
|
|
671
|
-
</code></pre>
|
|
672
|
-
|
|
673
|
-
<p>Link definitions can be placed anywhere in your Markdown document. I
|
|
674
|
-
tend to put them immediately after each paragraph in which they're
|
|
675
|
-
used, but if you want, you can put them all at the end of your
|
|
676
|
-
document, sort of like footnotes.</p>
|
|
677
|
-
|
|
678
|
-
<p>Here's an example of reference links in action:</p>
|
|
679
|
-
|
|
680
|
-
<pre><code>I get 10 times more traffic from [Google] [1] than from
|
|
681
|
-
[Yahoo] [2] or [MSN] [3].
|
|
682
|
-
|
|
683
|
-
[1]: http://google.com/ "Google"
|
|
684
|
-
[2]: http://search.yahoo.com/ "Yahoo Search"
|
|
685
|
-
[3]: http://search.msn.com/ "MSN Search"
|
|
686
|
-
</code></pre>
|
|
687
|
-
|
|
688
|
-
<p>Using the implicit link name shortcut, you could instead write:</p>
|
|
689
|
-
|
|
690
|
-
<pre><code>I get 10 times more traffic from [Google][] than from
|
|
691
|
-
[Yahoo][] or [MSN][].
|
|
692
|
-
|
|
693
|
-
[google]: http://google.com/ "Google"
|
|
694
|
-
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
|
|
695
|
-
[msn]: http://search.msn.com/ "MSN Search"
|
|
696
|
-
</code></pre>
|
|
697
|
-
|
|
698
|
-
<p>Both of the above examples will produce the following HTML output:</p>
|
|
699
|
-
|
|
700
|
-
<pre><code><p>I get 10 times more traffic from <a href="http://google.com/"
|
|
701
|
-
title="Google">Google</a> than from
|
|
702
|
-
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
|
|
703
|
-
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
|
|
704
|
-
</code></pre>
|
|
705
|
-
|
|
706
|
-
<p>For comparison, here is the same paragraph written using
|
|
707
|
-
Markdown's inline link style:</p>
|
|
708
|
-
|
|
709
|
-
<pre><code>I get 10 times more traffic from [Google](http://google.com/ "Google")
|
|
710
|
-
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
|
|
711
|
-
[MSN](http://search.msn.com/ "MSN Search").
|
|
712
|
-
</code></pre>
|
|
713
|
-
|
|
714
|
-
<p>The point of reference-style links is not that they're easier to
|
|
715
|
-
write. The point is that with reference-style links, your document
|
|
716
|
-
source is vastly more readable. Compare the above examples: using
|
|
717
|
-
reference-style links, the paragraph itself is only 81 characters
|
|
718
|
-
long; with inline-style links, it's 176 characters; and as raw HTML,
|
|
719
|
-
it's 234 characters. In the raw HTML, there's more markup than there
|
|
720
|
-
is text.</p>
|
|
721
|
-
|
|
722
|
-
<p>With Markdown's reference-style links, a source document much more
|
|
723
|
-
closely resembles the final output, as rendered in a browser. By
|
|
724
|
-
allowing you to move the markup-related metadata out of the paragraph,
|
|
725
|
-
you can add links without interrupting the narrative flow of your
|
|
726
|
-
prose.</p>
|
|
727
|
-
|
|
728
|
-
<h3 id="em">Emphasis</h3>
|
|
729
|
-
|
|
730
|
-
<p>Markdown treats asterisks (<code>*</code>) and underscores (<code>_</code>) as indicators of
|
|
731
|
-
emphasis. Text wrapped with one <code>*</code> or <code>_</code> will be wrapped with an
|
|
732
|
-
HTML <code><em></code> tag; double <code>*</code>'s or <code>_</code>'s will be wrapped with an HTML
|
|
733
|
-
<code><strong></code> tag. E.g., this input:</p>
|
|
734
|
-
|
|
735
|
-
<pre><code>*single asterisks*
|
|
736
|
-
|
|
737
|
-
_single underscores_
|
|
738
|
-
|
|
739
|
-
**double asterisks**
|
|
740
|
-
|
|
741
|
-
__double underscores__
|
|
742
|
-
</code></pre>
|
|
743
|
-
|
|
744
|
-
<p>will produce:</p>
|
|
745
|
-
|
|
746
|
-
<pre><code><em>single asterisks</em>
|
|
747
|
-
|
|
748
|
-
<em>single underscores</em>
|
|
749
|
-
|
|
750
|
-
<strong>double asterisks</strong>
|
|
751
|
-
|
|
752
|
-
<strong>double underscores</strong>
|
|
753
|
-
</code></pre>
|
|
754
|
-
|
|
755
|
-
<p>You can use whichever style you prefer; the lone restriction is that
|
|
756
|
-
the same character must be used to open and close an emphasis span.</p>
|
|
757
|
-
|
|
758
|
-
<p>Emphasis can be used in the middle of a word:</p>
|
|
759
|
-
|
|
760
|
-
<pre><code>un*fucking*believable
|
|
761
|
-
</code></pre>
|
|
762
|
-
|
|
763
|
-
<p>But if you surround an <code>*</code> or <code>_</code> with spaces, it'll be treated as a
|
|
764
|
-
literal asterisk or underscore.</p>
|
|
765
|
-
|
|
766
|
-
<p>To produce a literal asterisk or underscore at a position where it
|
|
767
|
-
would otherwise be used as an emphasis delimiter, you can backslash
|
|
768
|
-
escape it:</p>
|
|
769
|
-
|
|
770
|
-
<pre><code>\*this text is surrounded by literal asterisks\*
|
|
771
|
-
</code></pre>
|
|
772
|
-
|
|
773
|
-
<h3 id="code">Code</h3>
|
|
774
|
-
|
|
775
|
-
<p>To indicate a span of code, wrap it with backtick quotes (<code>`</code>).
|
|
776
|
-
Unlike a pre-formatted code block, a code span indicates code within a
|
|
777
|
-
normal paragraph. For example:</p>
|
|
778
|
-
|
|
779
|
-
<pre><code>Use the `printf()` function.
|
|
780
|
-
</code></pre>
|
|
781
|
-
|
|
782
|
-
<p>will produce:</p>
|
|
783
|
-
|
|
784
|
-
<pre><code><p>Use the <code>printf()</code> function.</p>
|
|
785
|
-
</code></pre>
|
|
786
|
-
|
|
787
|
-
<p>To include a literal backtick character within a code span, you can use
|
|
788
|
-
multiple backticks as the opening and closing delimiters:</p>
|
|
789
|
-
|
|
790
|
-
<pre><code>``There is a literal backtick (`) here.``
|
|
791
|
-
</code></pre>
|
|
792
|
-
|
|
793
|
-
<p>which will produce this:</p>
|
|
794
|
-
|
|
795
|
-
<pre><code><p><code>There is a literal backtick (`) here.</code></p>
|
|
796
|
-
</code></pre>
|
|
797
|
-
|
|
798
|
-
<p>The backtick delimiters surrounding a code span may include spaces --
|
|
799
|
-
one after the opening, one before the closing. This allows you to place
|
|
800
|
-
literal backtick characters at the beginning or end of a code span:</p>
|
|
801
|
-
|
|
802
|
-
<pre><code>A single backtick in a code span: `` ` ``
|
|
803
|
-
|
|
804
|
-
A backtick-delimited string in a code span: `` `foo` ``
|
|
805
|
-
</code></pre>
|
|
806
|
-
|
|
807
|
-
<p>will produce:</p>
|
|
808
|
-
|
|
809
|
-
<pre><code><p>A single backtick in a code span: <code>`</code></p>
|
|
810
|
-
|
|
811
|
-
<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
|
|
812
|
-
</code></pre>
|
|
813
|
-
|
|
814
|
-
<p>With a code span, ampersands and angle brackets are encoded as HTML
|
|
815
|
-
entities automatically, which makes it easy to include example HTML
|
|
816
|
-
tags. Markdown will turn this:</p>
|
|
817
|
-
|
|
818
|
-
<pre><code>Please don't use any `<blink>` tags.
|
|
819
|
-
</code></pre>
|
|
820
|
-
|
|
821
|
-
<p>into:</p>
|
|
822
|
-
|
|
823
|
-
<pre><code><p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
|
|
824
|
-
</code></pre>
|
|
825
|
-
|
|
826
|
-
<p>You can write this:</p>
|
|
827
|
-
|
|
828
|
-
<pre><code>`&#8212;` is the decimal-encoded equivalent of `&mdash;`.
|
|
829
|
-
</code></pre>
|
|
830
|
-
|
|
831
|
-
<p>to produce:</p>
|
|
832
|
-
|
|
833
|
-
<pre><code><p><code>&amp;#8212;</code> is the decimal-encoded
|
|
834
|
-
equivalent of <code>&amp;mdash;</code>.</p>
|
|
835
|
-
</code></pre>
|
|
836
|
-
|
|
837
|
-
<h3 id="img">Images</h3>
|
|
838
|
-
|
|
839
|
-
<p>Admittedly, it's fairly difficult to devise a "natural" syntax for
|
|
840
|
-
placing images into a plain text document format.</p>
|
|
841
|
-
|
|
842
|
-
<p>Markdown uses an image syntax that is intended to resemble the syntax
|
|
843
|
-
for links, allowing for two styles: <em>inline</em> and <em>reference</em>.</p>
|
|
844
|
-
|
|
845
|
-
<p>Inline image syntax looks like this:</p>
|
|
846
|
-
|
|
847
|
-
<pre><code>
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
</code></pre>
|
|
851
|
-
|
|
852
|
-
<p>That is:</p>
|
|
853
|
-
|
|
854
|
-
<ul>
|
|
855
|
-
<li>An exclamation mark: <code>!</code>;</li>
|
|
856
|
-
<li>followed by a set of square brackets, containing the <code>alt</code>
|
|
857
|
-
attribute text for the image;</li>
|
|
858
|
-
<li>followed by a set of parentheses, containing the URL or path to
|
|
859
|
-
the image, and an optional <code>title</code> attribute enclosed in double
|
|
860
|
-
or single quotes.</li>
|
|
861
|
-
</ul>
|
|
862
|
-
|
|
863
|
-
<p>Reference-style image syntax looks like this:</p>
|
|
864
|
-
|
|
865
|
-
<pre><code>![Alt text][id]
|
|
866
|
-
</code></pre>
|
|
867
|
-
|
|
868
|
-
<p>Where "id" is the name of a defined image reference. Image references
|
|
869
|
-
are defined using syntax identical to link references:</p>
|
|
870
|
-
|
|
871
|
-
<pre><code>[id]: url/to/image "Optional title attribute"
|
|
872
|
-
</code></pre>
|
|
873
|
-
|
|
874
|
-
<p>As of this writing, Markdown has no syntax for specifying the
|
|
875
|
-
dimensions of an image; if this is important to you, you can simply
|
|
876
|
-
use regular HTML <code><img></code> tags.</p>
|
|
877
|
-
|
|
878
|
-
<hr />
|
|
879
|
-
|
|
880
|
-
<h2 id="misc">Miscellaneous</h2>
|
|
881
|
-
|
|
882
|
-
<h3 id="autolink">Automatic Links</h3>
|
|
883
|
-
|
|
884
|
-
<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>
|
|
885
|
-
|
|
886
|
-
<pre><code><http://example.com/>
|
|
887
|
-
</code></pre>
|
|
888
|
-
|
|
889
|
-
<p>Markdown will turn this into:</p>
|
|
890
|
-
|
|
891
|
-
<pre><code><a href="http://example.com/">http://example.com/</a>
|
|
892
|
-
</code></pre>
|
|
893
|
-
|
|
894
|
-
<p>Automatic links for email addresses work similarly, except that
|
|
895
|
-
Markdown will also perform a bit of randomized decimal and hex
|
|
896
|
-
entity-encoding to help obscure your address from address-harvesting
|
|
897
|
-
spambots. For example, Markdown will turn this:</p>
|
|
898
|
-
|
|
899
|
-
<pre><code><address@example.com>
|
|
900
|
-
</code></pre>
|
|
901
|
-
|
|
902
|
-
<p>into something like this:</p>
|
|
903
|
-
|
|
904
|
-
<pre><code><a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
|
|
905
|
-
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
|
|
906
|
-
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
|
|
907
|
-
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
|
|
908
|
-
</code></pre>
|
|
909
|
-
|
|
910
|
-
<p>which will render in a browser as a clickable link to "address@example.com".</p>
|
|
911
|
-
|
|
912
|
-
<p>(This sort of entity-encoding trick will indeed fool many, if not
|
|
913
|
-
most, address-harvesting bots, but it definitely won't fool all of
|
|
914
|
-
them. It's better than nothing, but an address published in this way
|
|
915
|
-
will probably eventually start receiving spam.)</p>
|
|
916
|
-
|
|
917
|
-
<h3 id="backslash">Backslash Escapes</h3>
|
|
918
|
-
|
|
919
|
-
<p>Markdown allows you to use backslash escapes to generate literal
|
|
920
|
-
characters which would otherwise have special meaning in Markdown's
|
|
921
|
-
formatting syntax. For example, if you wanted to surround a word with
|
|
922
|
-
literal asterisks (instead of an HTML <code><em></code> tag), you can backslashes
|
|
923
|
-
before the asterisks, like this:</p>
|
|
924
|
-
|
|
925
|
-
<pre><code>\*literal asterisks\*
|
|
926
|
-
</code></pre>
|
|
927
|
-
|
|
928
|
-
<p>Markdown provides backslash escapes for the following characters:</p>
|
|
929
|
-
|
|
930
|
-
<pre><code>\ backslash
|
|
931
|
-
` backtick
|
|
932
|
-
* asterisk
|
|
933
|
-
_ underscore
|
|
934
|
-
{} curly braces
|
|
935
|
-
[] square brackets
|
|
936
|
-
() parentheses
|
|
937
|
-
# hash mark
|
|
938
|
-
+ plus sign
|
|
939
|
-
- minus sign (hyphen)
|
|
940
|
-
. dot
|
|
941
|
-
! exclamation mark
|
|
942
|
-
</code></pre>
|