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