remi-maruku 0.5.9
Sign up to get free protection for your applications and to get access to all the features.
- data/Rakefile +73 -0
- data/bin/marudown +29 -0
- data/bin/maruku +176 -0
- data/bin/marutest +338 -0
- data/bin/marutex +31 -0
- data/docs/changelog.md +334 -0
- data/docs/div_syntax.md +36 -0
- data/docs/entity_test.md +23 -0
- data/docs/markdown_syntax.md +899 -0
- data/docs/maruku.md +346 -0
- data/docs/math.md +194 -0
- data/docs/other_stuff.md +51 -0
- data/docs/proposal.md +309 -0
- data/lib/maruku.rb +141 -0
- data/lib/maruku/attributes.rb +227 -0
- data/lib/maruku/defaults.rb +70 -0
- data/lib/maruku/errors_management.rb +92 -0
- data/lib/maruku/ext/div.rb +100 -0
- data/lib/maruku/ext/math.rb +41 -0
- data/lib/maruku/ext/math/elements.rb +27 -0
- data/lib/maruku/ext/math/latex_fix.rb +11 -0
- data/lib/maruku/ext/math/mathml_engines/blahtex.rb +104 -0
- data/lib/maruku/ext/math/mathml_engines/itex2mml.rb +29 -0
- data/lib/maruku/ext/math/mathml_engines/none.rb +20 -0
- data/lib/maruku/ext/math/mathml_engines/ritex.rb +24 -0
- data/lib/maruku/ext/math/parsing.rb +105 -0
- data/lib/maruku/ext/math/to_html.rb +170 -0
- data/lib/maruku/ext/math/to_latex.rb +22 -0
- data/lib/maruku/helpers.rb +260 -0
- data/lib/maruku/input/charsource.rb +326 -0
- data/lib/maruku/input/extensions.rb +69 -0
- data/lib/maruku/input/html_helper.rb +189 -0
- data/lib/maruku/input/linesource.rb +111 -0
- data/lib/maruku/input/parse_block.rb +613 -0
- data/lib/maruku/input/parse_doc.rb +227 -0
- data/lib/maruku/input/parse_span_better.rb +732 -0
- data/lib/maruku/input/rubypants.rb +225 -0
- data/lib/maruku/input/type_detection.rb +144 -0
- data/lib/maruku/input_textile2/t2_parser.rb +163 -0
- data/lib/maruku/maruku.rb +33 -0
- data/lib/maruku/output/s5/fancy.rb +756 -0
- data/lib/maruku/output/s5/to_s5.rb +125 -0
- data/lib/maruku/output/to_html.rb +971 -0
- data/lib/maruku/output/to_latex.rb +563 -0
- data/lib/maruku/output/to_latex_entities.rb +367 -0
- data/lib/maruku/output/to_latex_strings.rb +64 -0
- data/lib/maruku/output/to_markdown.rb +164 -0
- data/lib/maruku/output/to_s.rb +53 -0
- data/lib/maruku/string_utils.rb +191 -0
- data/lib/maruku/structures.rb +165 -0
- data/lib/maruku/structures_inspect.rb +87 -0
- data/lib/maruku/structures_iterators.rb +61 -0
- data/lib/maruku/tests/benchmark.rb +82 -0
- data/lib/maruku/tests/new_parser.rb +370 -0
- data/lib/maruku/tests/tests.rb +136 -0
- data/lib/maruku/textile2.rb +1 -0
- data/lib/maruku/toc.rb +199 -0
- data/lib/maruku/usage/example1.rb +33 -0
- data/lib/maruku/version.rb +40 -0
- data/tests/bugs/code_in_links.md +16 -0
- data/tests/bugs/complex_escaping.md +4 -0
- data/tests/math/syntax.md +46 -0
- data/tests/math_usage/document.md +13 -0
- data/tests/others/abbreviations.md +11 -0
- data/tests/others/blank.md +4 -0
- data/tests/others/code.md +5 -0
- data/tests/others/code2.md +8 -0
- data/tests/others/code3.md +16 -0
- data/tests/others/email.md +4 -0
- data/tests/others/entities.md +19 -0
- data/tests/others/escaping.md +16 -0
- data/tests/others/extra_dl.md +101 -0
- data/tests/others/extra_header_id.md +13 -0
- data/tests/others/extra_table1.md +40 -0
- data/tests/others/footnotes.md +17 -0
- data/tests/others/headers.md +10 -0
- data/tests/others/hrule.md +10 -0
- data/tests/others/images.md +20 -0
- data/tests/others/inline_html.md +42 -0
- data/tests/others/links.md +38 -0
- data/tests/others/list1.md +4 -0
- data/tests/others/list2.md +5 -0
- data/tests/others/list3.md +8 -0
- data/tests/others/lists.md +32 -0
- data/tests/others/lists_after_paragraph.md +44 -0
- data/tests/others/lists_ol.md +39 -0
- data/tests/others/misc_sw.md +105 -0
- data/tests/others/one.md +1 -0
- data/tests/others/paragraphs.md +13 -0
- data/tests/others/sss06.md +352 -0
- data/tests/others/test.md +4 -0
- data/tests/s5/s5profiling.md +48 -0
- data/tests/unittest/abbreviations.md +72 -0
- data/tests/unittest/alt.md +30 -0
- data/tests/unittest/attributes/att2.md +34 -0
- data/tests/unittest/attributes/att3.md +45 -0
- data/tests/unittest/attributes/attributes.md +82 -0
- data/tests/unittest/attributes/circular.md +43 -0
- data/tests/unittest/attributes/default.md +38 -0
- data/tests/unittest/blank.md +39 -0
- data/tests/unittest/blanks_in_code.md +106 -0
- data/tests/unittest/bug_def.md +29 -0
- data/tests/unittest/bug_table.md +67 -0
- data/tests/unittest/code.md +53 -0
- data/tests/unittest/code2.md +46 -0
- data/tests/unittest/code3.md +102 -0
- data/tests/unittest/data_loss.md +42 -0
- data/tests/unittest/divs/div1.md +204 -0
- data/tests/unittest/divs/div2.md +34 -0
- data/tests/unittest/divs/div3_nest.md +62 -0
- data/tests/unittest/easy.md +28 -0
- data/tests/unittest/email.md +33 -0
- data/tests/unittest/encoding/iso-8859-1.md +38 -0
- data/tests/unittest/encoding/utf-8.md +33 -0
- data/tests/unittest/entities.md +124 -0
- data/tests/unittest/escaping.md +89 -0
- data/tests/unittest/extra_dl.md +72 -0
- data/tests/unittest/extra_header_id.md +86 -0
- data/tests/unittest/extra_table1.md +55 -0
- data/tests/unittest/footnotes.md +126 -0
- data/tests/unittest/headers.md +54 -0
- data/tests/unittest/hex_entities.md +50 -0
- data/tests/unittest/hrule.md +60 -0
- data/tests/unittest/html2.md +38 -0
- data/tests/unittest/html3.md +47 -0
- data/tests/unittest/html4.md +42 -0
- data/tests/unittest/html5.md +38 -0
- data/tests/unittest/ie.md +82 -0
- data/tests/unittest/images.md +114 -0
- data/tests/unittest/images2.md +46 -0
- data/tests/unittest/inline_html.md +260 -0
- data/tests/unittest/inline_html2.md +36 -0
- data/tests/unittest/links.md +197 -0
- data/tests/unittest/list1.md +66 -0
- data/tests/unittest/list2.md +76 -0
- data/tests/unittest/list3.md +88 -0
- data/tests/unittest/list4.md +116 -0
- data/tests/unittest/lists.md +241 -0
- data/tests/unittest/lists11.md +31 -0
- data/tests/unittest/lists6.md +54 -0
- data/tests/unittest/lists7.md +79 -0
- data/tests/unittest/lists7b.md +136 -0
- data/tests/unittest/lists8.md +83 -0
- data/tests/unittest/lists9.md +85 -0
- data/tests/unittest/lists_after_paragraph.md +268 -0
- data/tests/unittest/lists_ol.md +324 -0
- data/tests/unittest/loss.md +29 -0
- data/tests/unittest/math/equations.md +69 -0
- data/tests/unittest/math/inline.md +66 -0
- data/tests/unittest/math/math2.md +110 -0
- data/tests/unittest/math/notmath.md +40 -0
- data/tests/unittest/math/table.md +43 -0
- data/tests/unittest/math/table2.md +60 -0
- data/tests/unittest/misc_sw.md +615 -0
- data/tests/unittest/notyet/escape.md +36 -0
- data/tests/unittest/notyet/header_after_par.md +81 -0
- data/tests/unittest/notyet/ticks.md +31 -0
- data/tests/unittest/notyet/triggering.md +206 -0
- data/tests/unittest/olist.md +64 -0
- data/tests/unittest/one.md +28 -0
- data/tests/unittest/paragraph.md +29 -0
- data/tests/unittest/paragraph_rules/dont_merge_ref.md +57 -0
- data/tests/unittest/paragraph_rules/tab_is_blank.md +39 -0
- data/tests/unittest/paragraphs.md +66 -0
- data/tests/unittest/pending/amps.md +29 -0
- data/tests/unittest/pending/empty_cells.md +53 -0
- data/tests/unittest/pending/link.md +103 -0
- data/tests/unittest/recover/recover_links.md +28 -0
- data/tests/unittest/references/long_example.md +88 -0
- data/tests/unittest/references/spaces_and_numbers.md +28 -0
- data/tests/unittest/smartypants.md +171 -0
- data/tests/unittest/syntax_hl.md +80 -0
- data/tests/unittest/table_attributes.md +52 -0
- data/tests/unittest/test.md +32 -0
- data/tests/unittest/wrapping.md +88 -0
- data/tests/unittest/xml.md +54 -0
- data/tests/unittest/xml2.md +34 -0
- data/tests/unittest/xml3.md +44 -0
- data/tests/unittest/xml_instruction.md +72 -0
- data/tests/utf8-files/simple.md +1 -0
- data/unit_test_block.sh +5 -0
- data/unit_test_span.sh +2 -0
- metadata +243 -0
data/bin/marutex
ADDED
@@ -0,0 +1,31 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
require 'maruku'
|
4
|
+
|
5
|
+
if File.basename($0) =~ /^marutex/
|
6
|
+
# Convert each file
|
7
|
+
ARGV.each do |f|
|
8
|
+
puts "Opening #{f}"
|
9
|
+
|
10
|
+
# read file content
|
11
|
+
input = File.open(f,'r').read
|
12
|
+
|
13
|
+
# create Maruku
|
14
|
+
doc = Maruku.new(input)
|
15
|
+
# convert to a complete html document
|
16
|
+
latex = doc.to_latex_document
|
17
|
+
|
18
|
+
# write to file
|
19
|
+
dir = File.dirname(f)
|
20
|
+
job = File.join(dir, File.basename(f, File.extname(f)))
|
21
|
+
filename = job + ".tex"
|
22
|
+
|
23
|
+
File.open(filename,'w') do |f| f.puts latex end
|
24
|
+
|
25
|
+
# run twice for cross references
|
26
|
+
system "pdflatex '#{job}' '-output-directory=#{dir}' "
|
27
|
+
system "pdflatex '#{job}' '-output-directory=#{dir}' "
|
28
|
+
|
29
|
+
# system "open #{job}.pdf"
|
30
|
+
end
|
31
|
+
end
|
data/docs/changelog.md
ADDED
@@ -0,0 +1,334 @@
|
|
1
|
+
CSS: style.css
|
2
|
+
LaTeX CJK: true
|
3
|
+
HTML use syntax: true
|
4
|
+
|
5
|
+
<!-- #### Changes in the development version (**not yet released**) #### {#last} -->
|
6
|
+
|
7
|
+
#### Changes in 0.5.6 #### {#stable}
|
8
|
+
|
9
|
+
* News:
|
10
|
+
|
11
|
+
- Now Maruku is in the official Gentoo Portage tree (done by [Aggelos Orfanakos])
|
12
|
+
|
13
|
+
* New stuff:
|
14
|
+
|
15
|
+
- Attribute `maruku_signature` defaults to false. (many people asked this)
|
16
|
+
- unittests scripts are included in the distribution.
|
17
|
+
- New attribute `filter_html`: if true, raw HTML/XML is discarded. (asked by Marik)
|
18
|
+
- Command line: if output file is `-`, Maruku writes to stdout.
|
19
|
+
|
20
|
+
* Bug fixes:
|
21
|
+
|
22
|
+
* Another tiny bug in HTML parsing.
|
23
|
+
* In latex, `\linebreak` was used instead of `\newline` (reported by Sam Kleinman)
|
24
|
+
* Fixed bug with non-alpha numeric characters in ref.ids (reported by Aggelos Orfanakos)
|
25
|
+
|
26
|
+
|
27
|
+
* Pending bugs/feature requests:
|
28
|
+
|
29
|
+
- Maruku does not allow 3-space indented lists.
|
30
|
+
- Lists item whose first character is UTF8 are not recognized (reported by Aggelos Orfanakos)
|
31
|
+
- Maruku cannot output `"`-delimited attributes, because `REXML` does not support it.
|
32
|
+
|
33
|
+
[Aggelos Orfanakos]: http://agorf.gr/
|
34
|
+
|
35
|
+
#### Changes in 0.5.5 ####
|
36
|
+
|
37
|
+
* Features:
|
38
|
+
|
39
|
+
* Input of HTML numeric entities:
|
40
|
+
|
41
|
+
Examples of numeric character references include © or ©
|
42
|
+
for the copyright symbol, Α or Α for the Greek capital
|
43
|
+
letter alpha, and ا or ا for the Arabic letter alef.
|
44
|
+
|
45
|
+
> Examples of numeric character references include © or ©
|
46
|
+
> for the copyright symbol, Α or Α for the Greek capital
|
47
|
+
> letter alpha, and ا or ا for the Arabic letter alef.
|
48
|
+
|
49
|
+
* Bug fixes:
|
50
|
+
|
51
|
+
* Alt text was ignored for images.
|
52
|
+
* Fixed minor bug in reading HTML inside paragraph.
|
53
|
+
* Changed rules for block-level HTML to make it similar to Markdown.pl.
|
54
|
+
For example:
|
55
|
+
|
56
|
+
Paragraph
|
57
|
+
<div></div>
|
58
|
+
|
59
|
+
will be translated to
|
60
|
+
|
61
|
+
<p>Paragraph
|
62
|
+
<div></div></p>
|
63
|
+
|
64
|
+
while this:
|
65
|
+
|
66
|
+
Paragraph
|
67
|
+
|
68
|
+
<div></div>
|
69
|
+
|
70
|
+
becomes
|
71
|
+
|
72
|
+
<p>Paragraph</p>
|
73
|
+
|
74
|
+
<div></div>
|
75
|
+
|
76
|
+
* **Pending bugs**: there are some problems when parsing lists. It is difficult
|
77
|
+
to get it right because the spec is very fuzzy. At the moment, list items
|
78
|
+
cannot be indented by more than 1 space.
|
79
|
+
|
80
|
+
#### Changes in 0.5.4 ####
|
81
|
+
|
82
|
+
* Features:
|
83
|
+
|
84
|
+
* [All HTML attributes](http://www.w3.org/TR/html4/index/attributes.html) are supported.
|
85
|
+
|
86
|
+
> Science is a wonderful thing if one does not
|
87
|
+
> have to earn one's living at it.
|
88
|
+
{: cite="http://en.wikiquote.org/wiki/Albert_Einstein"}
|
89
|
+
|
90
|
+
* Attribute `doc_prefix`.
|
91
|
+
|
92
|
+
* Math:
|
93
|
+
|
94
|
+
* `\begin{equation}` and `\end{equation}` are understood.
|
95
|
+
* Math parsing enabled per-instance using the `math_enabled` attribute.
|
96
|
+
* `math_numbered` attribute.
|
97
|
+
|
98
|
+
* Bug fixes:
|
99
|
+
|
100
|
+
* Runs quietly with `ruby -w`.
|
101
|
+
* Fixed a bug which could cause data-loss when reading indented lines.
|
102
|
+
|
103
|
+
|
104
|
+
#### Changes in 0.5.3 ####
|
105
|
+
|
106
|
+
* Features:
|
107
|
+
|
108
|
+
* [All HTML `table` attributes](http://www.w3.org/TR/html4/struct/tables.html#h-11.2.1)
|
109
|
+
can be used (`summary`, `width`, `frame`, `rules`,
|
110
|
+
`border`, `cellspacing`, `cellpadding`).
|
111
|
+
|
112
|
+
The next version will hopefully use all HTML attributes.
|
113
|
+
|
114
|
+
|
115
|
+
<!-- A version of Markdown that is more Japanese or something -->
|
116
|
+
|
117
|
+
* Bug fixes:
|
118
|
+
|
119
|
+
* Crash on this line: (found by Aggelos Orfanakos)
|
120
|
+
|
121
|
+
[test][]:
|
122
|
+
|
123
|
+
* Regression with attribute system (found by Charles)
|
124
|
+
|
125
|
+
#### Changes in 0.5.1 ####
|
126
|
+
|
127
|
+
* Bug fixes:
|
128
|
+
|
129
|
+
* Workaround for Internet Explorer bug:
|
130
|
+
be very sure that `'` is always written as `'`.
|
131
|
+
|
132
|
+
* Support for empty images ref: `![image]` and `![image][]`.
|
133
|
+
|
134
|
+
* Fixed bug in parsing attribute lists definitions.
|
135
|
+
|
136
|
+
* Minor things:
|
137
|
+
|
138
|
+
* Now code blocks are written as a `<code>` element inside a `<pre>`, and
|
139
|
+
`<code>` elements have both `class` and `lang` attributes set
|
140
|
+
to the specified language.
|
141
|
+
|
142
|
+
Example:
|
143
|
+
|
144
|
+
Example
|
145
|
+
{:lang=ruby}
|
146
|
+
{:lang=markdown}
|
147
|
+
|
148
|
+
produces:
|
149
|
+
|
150
|
+
<pre><code class='ruby' lang='ruby'>Example</code></pre>
|
151
|
+
{:lang=xml}
|
152
|
+
|
153
|
+
#### Changes in 0.5.0 ####
|
154
|
+
|
155
|
+
* Syntax changes:
|
156
|
+
|
157
|
+
* Compatibility with newest Markdown.pl: `[text]` as a synonim of `[text][]`.
|
158
|
+
|
159
|
+
* Meta data: the first IAL in a span environment now refers to the parent.
|
160
|
+
This makes it possible to set attributes for cells:
|
161
|
+
|
162
|
+
Head | Head |
|
163
|
+
---------------+-------+--
|
164
|
+
{:r} Hello + ...
|
165
|
+
|
166
|
+
{:r: scope='row'}
|
167
|
+
|
168
|
+
The first cell will have the `scope` attribute set to `row`.
|
169
|
+
|
170
|
+
* New settings:
|
171
|
+
|
172
|
+
* Disable the Maruku signature by setting `maruku signature: false`
|
173
|
+
|
174
|
+
* Stricter doctype. By the way -- did I mention it? --
|
175
|
+
**Maruku HTML has always been proper validating XHTML strict**
|
176
|
+
(if a page does not validate, please report it as a bug).
|
177
|
+
|
178
|
+
Of course, this only matters when using `maruku` as a standalone
|
179
|
+
program.
|
180
|
+
|
181
|
+
* I have updated the XHTML DTD used to support MathML:
|
182
|
+
currently using XHTML+MathML+SVG.
|
183
|
+
* Content-type set to `application/xhtml+xml`
|
184
|
+
* All entities are written as numeric entities.
|
185
|
+
|
186
|
+
* Bug fixes
|
187
|
+
|
188
|
+
* Many fixes in the code handling the sanitizing of inline HTML.
|
189
|
+
* `markdown=1` did not propagate to children.
|
190
|
+
* LaTeX: An exception was raised if an unknown entity was used.
|
191
|
+
|
192
|
+
#### Changes in 0.4.2 ####
|
193
|
+
|
194
|
+
* Adapted syntax to the [new meta-data proposal][proposal].
|
195
|
+
|
196
|
+
* Changes in LaTeX export:
|
197
|
+
|
198
|
+
* Links to external URLs are blue by default.
|
199
|
+
|
200
|
+
* New attributes: `latex_preamble` to add a custom preamble,
|
201
|
+
and `latex_cjk` to add packages for UTF-8 Japanese characters.
|
202
|
+
(**support for this is still shaky**). Example:
|
203
|
+
|
204
|
+
Title: my document
|
205
|
+
LaTeX CJK: true
|
206
|
+
LaTeX preamble: preamble.tex
|
207
|
+
|
208
|
+
Content
|
209
|
+
|
210
|
+
* Bug fixes
|
211
|
+
|
212
|
+
+ Images were not given `id` or `class` attributes.
|
213
|
+
|
214
|
+
+ Fixed bug in LaTeX export with handling of `<`,`>` enclosed URLs: `<google.com>`.
|
215
|
+
|
216
|
+
#### Changes in 0.4.1 aka "Typographer" ####
|
217
|
+
|
218
|
+
* Implemented SmartyPants support:
|
219
|
+
|
220
|
+
'Twas a "test" to 'remember' -- in the '90s
|
221
|
+
--- while I was <<ok>>. She was 6\"12\'.
|
222
|
+
> 'Twas a "test" to 'remember' -- in the '90s --- while I was <<ok>>.
|
223
|
+
> She was 6\"12\'.
|
224
|
+
|
225
|
+
I adapted the code from RubyPants.
|
226
|
+
|
227
|
+
* Server directives between `<? ?>` are properly preserved.
|
228
|
+
* Changes in LaTeX export:
|
229
|
+
|
230
|
+
* Now Japanese text rendering sort of works, using the following packages:
|
231
|
+
|
232
|
+
\usepackage[C40]{fontenc}
|
233
|
+
\usepackage[cjkjis]{ucs}
|
234
|
+
\usepackage[utf8x]{inputenc}
|
235
|
+
|
236
|
+
Nevertheless, I could only get bitmap fonts working -- probably it's a problem
|
237
|
+
with my setup.
|
238
|
+
|
239
|
+
A quick test: 日本、中国、ひらがな、カタカナ。
|
240
|
+
|
241
|
+
* Fixed bugs in rendering of immediate links.
|
242
|
+
* External packages are `require`d only if needed.
|
243
|
+
* More symbols supported.
|
244
|
+
See the symbol list
|
245
|
+
[in HTML](http://maruku.rubyforge.org/entity_test.html) and
|
246
|
+
[in PDF](http://maruku.rubyforge.org/entity_test.pdf).
|
247
|
+
|
248
|
+
|
249
|
+
#### Changes in 0.4 ####
|
250
|
+
|
251
|
+
* First implementation of [the new meta-data syntax][meta].
|
252
|
+
* General refactorization of the code and much cleaner error reporting.
|
253
|
+
* Created [the RDOC documentation][rdoc].
|
254
|
+
* The `add_whitespace` method took too much time -- it was O(n^2).
|
255
|
+
* Added unit-tests for block-level elements.
|
256
|
+
|
257
|
+
[rdoc]: http://maruku.rubyforge.org/rdoc/
|
258
|
+
[meta]: http://maruku.rubyforge.org/proposal.html
|
259
|
+
|
260
|
+
|
261
|
+
|
262
|
+
[Jacques Distler]: http://golem.ph.utexas.edu/~distler
|
263
|
+
[itex2MML]: http://golem.ph.utexas.edu/~distler/blog/itex2MML.html
|
264
|
+
[math]: http://rubyforge.maruku.org/math.html
|
265
|
+
|
266
|
+
|
267
|
+
#### Changes in 0.3 ####
|
268
|
+
|
269
|
+
* A real parser is used instead of a regexp-based system, also for span-level
|
270
|
+
elements.
|
271
|
+
|
272
|
+
Now Maruku is almost 2x faster than Bluecloth, while having more features.
|
273
|
+
|
274
|
+
Here are some benchmarks:
|
275
|
+
|
276
|
+
BlueCloth (to_html): parsing 0.00 sec + rendering 1.54 sec = 1.55 sec
|
277
|
+
Maruku (to_html): parsing 0.47 sec + rendering 0.38 sec = 0.85 sec
|
278
|
+
Maruku (to_latex): parsing 0.49 sec + rendering 0.25 sec = 0.73 sec
|
279
|
+
|
280
|
+
This is the result of running `lib/maruku/tests/benchmark.rb` on the Markdown
|
281
|
+
specification.
|
282
|
+
|
283
|
+
* Prettier HTML output by adding whitespace.
|
284
|
+
|
285
|
+
* Added a full suite of unit-tests for the span-level parser.
|
286
|
+
|
287
|
+
* Error management: Having a real parser, Maruku warns you about syntax issues.
|
288
|
+
|
289
|
+
The default action is to warn and try to continue. If you do this:
|
290
|
+
|
291
|
+
Maruku.new(string, {:on_error => :raise})
|
292
|
+
|
293
|
+
then syntax errors will cause an exception to be raised (you can catch this
|
294
|
+
and retry).
|
295
|
+
|
296
|
+
* Fixed a series of bugs in handling inline HTML code.
|
297
|
+
|
298
|
+
Immediate TODO-list:
|
299
|
+
|
300
|
+
* UTF-8 input/output works OK for HTML, however I am having pain trying to export
|
301
|
+
to LaTeX. I want at least Japanese characters support, so if you know how to
|
302
|
+
do this you are very welcome to give me an hand.
|
303
|
+
|
304
|
+
For example: in the HTML version, you should see accented characters in this
|
305
|
+
parenthesis:
|
306
|
+
|
307
|
+
> (àèìòù)
|
308
|
+
|
309
|
+
and Japanese text in these other parentheses:
|
310
|
+
|
311
|
+
> (カタカナで 私の 名前は アンドレア チェンシ です).
|
312
|
+
>
|
313
|
+
> (日本のガルは 大好き、でも、日本語は難しですから、そうぞ 英語話すガルを おしえてください).
|
314
|
+
|
315
|
+
In the LaTeX version, these do not appear. I know how to do LaTeX with
|
316
|
+
ISO-8859-1 encoding (European characters), but I'm struggling with half-baked
|
317
|
+
solutions for UTF-8 encoded documents.
|
318
|
+
|
319
|
+
* Implement the [new meta-data proposal][proposal].
|
320
|
+
|
321
|
+
* Exporting to Markdown (pretty printing).
|
322
|
+
|
323
|
+
* Exporting to HTML splitting in multiple files.
|
324
|
+
|
325
|
+
* RubyPants.
|
326
|
+
|
327
|
+
* Support for images in PDF.
|
328
|
+
|
329
|
+
|
330
|
+
[proposal]: http://maruku.rubyforge.org/proposal.html
|
331
|
+
[contact]: http://www.dis.uniroma1.it/~acensi/contact.html
|
332
|
+
[markdown-discuss]: http://six.pairlist.net/mailman/listinfo/markdown-discuss
|
333
|
+
[tracker]: http://rubyforge.org/tracker/?group_id=2795
|
334
|
+
|
data/docs/div_syntax.md
ADDED
@@ -0,0 +1,36 @@
|
|
1
|
+
## Option number 1 ##
|
2
|
+
|
3
|
+
* `[ ]{0,3}\+={2,}` pushes the stack
|
4
|
+
* `[ ]{0,3}\-={2,}` pops the stack
|
5
|
+
|
6
|
+
+================ {#id}
|
7
|
+
IAL can be put on the same line of a push
|
8
|
+
|
9
|
+
+== {#id2}
|
10
|
+
Or on the same line of a pop:
|
11
|
+
-==
|
12
|
+
|
13
|
+
-==============
|
14
|
+
|
15
|
+
## Option number 2 ##
|
16
|
+
|
17
|
+
Double braces:
|
18
|
+
|
19
|
+
{{
|
20
|
+
|
21
|
+
}}{}
|
22
|
+
|
23
|
+
I don't like, it gets too messy because there are
|
24
|
+
too many braces.
|
25
|
+
|
26
|
+
|
27
|
+
|
28
|
+
+================ {#id}
|
29
|
+
|
30
|
+
nested div:
|
31
|
+
|
32
|
+
+========================
|
33
|
+
inside nested DIV
|
34
|
+
-========================
|
35
|
+
|
36
|
+
-==============
|
data/docs/entity_test.md
ADDED
@@ -0,0 +1,23 @@
|
|
1
|
+
|
2
|
+
List of symbols supported by Maruku
|
3
|
+
===================================
|
4
|
+
|
5
|
+
<?maruku
|
6
|
+
MaRuKu::Out::Latex.need_entity_table
|
7
|
+
|
8
|
+
all = []
|
9
|
+
ENTITY_TABLE.each do |k, e|
|
10
|
+
if k.kind_of? String
|
11
|
+
all << (h=md_code("&#{e.html_entity};")) <<
|
12
|
+
" " << md_entity(e.html_entity) <<
|
13
|
+
" (" << (l=md_code(e.latex_string)) << ") \n" <<
|
14
|
+
md_entity('nbsp')<<md_entity('nbsp')<<md_entity('nbsp')
|
15
|
+
|
16
|
+
h.attributes[:code_background_color] = '#eef'
|
17
|
+
l.attributes[:code_background_color] = '#ffe'
|
18
|
+
end
|
19
|
+
end
|
20
|
+
@doc.children.push md_par(all)
|
21
|
+
|
22
|
+
?>
|
23
|
+
|
@@ -0,0 +1,899 @@
|
|
1
|
+
css: style.css
|
2
|
+
|
3
|
+
Markdown: Syntax
|
4
|
+
================
|
5
|
+
|
6
|
+
<ul id="ProjectSubmenu">
|
7
|
+
<li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
|
8
|
+
<li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
|
9
|
+
<li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
|
10
|
+
<li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
|
11
|
+
<li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
|
12
|
+
</ul>
|
13
|
+
|
14
|
+
|
15
|
+
* [Overview](#overview)
|
16
|
+
* [Philosophy](#philosophy)
|
17
|
+
* [Inline HTML](#html)
|
18
|
+
* [Automatic Escaping for Special Characters](#autoescape)
|
19
|
+
* [Block Elements](#block)
|
20
|
+
* [Paragraphs and Line Breaks](#p)
|
21
|
+
* [Headers](#header)
|
22
|
+
* [Blockquotes](#blockquote)
|
23
|
+
* [Lists](#list)
|
24
|
+
* [Code Blocks](#precode)
|
25
|
+
* [Horizontal Rules](#hr)
|
26
|
+
* [Span Elements](#span)
|
27
|
+
* [Links](#link)
|
28
|
+
* [Emphasis](#em)
|
29
|
+
* [Code](#code)
|
30
|
+
* [Images](#img)
|
31
|
+
* [Miscellaneous](#misc)
|
32
|
+
* [Backslash Escapes](#backslash)
|
33
|
+
* [Automatic Links](#autolink)
|
34
|
+
|
35
|
+
|
36
|
+
**Note:** This document is itself written using Markdown; you
|
37
|
+
can [see the source for it by adding '.text' to the URL][src].
|
38
|
+
|
39
|
+
[src]: /projects/markdown/syntax.text
|
40
|
+
|
41
|
+
* * *
|
42
|
+
|
43
|
+
<h2 id="overview">Overview</h2>
|
44
|
+
|
45
|
+
<h3 id="philosophy">Philosophy</h3>
|
46
|
+
|
47
|
+
Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
|
48
|
+
|
49
|
+
Readability, however, is emphasized above all else. A Markdown-formatted
|
50
|
+
document should be publishable as-is, as plain text, without looking
|
51
|
+
like it's been marked up with tags or formatting instructions. While
|
52
|
+
Markdown's syntax has been influenced by several existing text-to-HTML
|
53
|
+
filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
|
54
|
+
[Grutatext] [5], and [EtText] [6] -- the single biggest source of
|
55
|
+
inspiration for Markdown's syntax is the format of plain text email.
|
56
|
+
|
57
|
+
[1]: http://docutils.sourceforge.net/mirror/setext.html
|
58
|
+
[2]: http://www.aaronsw.com/2002/atx/
|
59
|
+
[3]: http://textism.com/tools/textile/
|
60
|
+
[4]: http://docutils.sourceforge.net/rst.html
|
61
|
+
[5]: http://www.triptico.com/software/grutatxt.html
|
62
|
+
[6]: http://ettext.taint.org/doc/
|
63
|
+
|
64
|
+
To this end, Markdown's syntax is comprised entirely of punctuation
|
65
|
+
characters, which punctuation characters have been carefully chosen so
|
66
|
+
as to look like what they mean. E.g., asterisks around a word actually
|
67
|
+
look like \*emphasis\*. Markdown lists look like, well, lists. Even
|
68
|
+
blockquotes look like quoted passages of text, assuming you've ever
|
69
|
+
used email.
|
70
|
+
|
71
|
+
|
72
|
+
|
73
|
+
<h3 id="html">Inline HTML</h3>
|
74
|
+
|
75
|
+
Markdown's syntax is intended for one purpose: to be used as a
|
76
|
+
format for *writing* for the web.
|
77
|
+
|
78
|
+
Markdown is not a replacement for HTML, or even close to it. Its
|
79
|
+
syntax is very small, corresponding only to a very small subset of
|
80
|
+
HTML tags. The idea is *not* to create a syntax that makes it easier
|
81
|
+
to insert HTML tags. In my opinion, HTML tags are already easy to
|
82
|
+
insert. The idea for Markdown is to make it easy to read, write, and
|
83
|
+
edit prose. HTML is a *publishing* format; Markdown is a *writing*
|
84
|
+
format. Thus, Markdown's formatting syntax only addresses issues that
|
85
|
+
can be conveyed in plain text.
|
86
|
+
|
87
|
+
For any markup that is not covered by Markdown's syntax, you simply
|
88
|
+
use HTML itself. There's no need to preface it or delimit it to
|
89
|
+
indicate that you're switching from Markdown to HTML; you just use
|
90
|
+
the tags.
|
91
|
+
|
92
|
+
The only restrictions are that block-level HTML elements -- e.g. `<div>`,
|
93
|
+
`<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
|
94
|
+
content by blank lines, and the start and end tags of the block should
|
95
|
+
not be indented with tabs or spaces. Markdown is smart enough not
|
96
|
+
to add extra (unwanted) `<p>` tags around HTML block-level tags.
|
97
|
+
|
98
|
+
For example, to add an HTML table to a Markdown article:
|
99
|
+
|
100
|
+
This is a regular paragraph.
|
101
|
+
|
102
|
+
<table>
|
103
|
+
<tr>
|
104
|
+
<td>Foo</td>
|
105
|
+
</tr>
|
106
|
+
</table>
|
107
|
+
|
108
|
+
This is another regular paragraph.
|
109
|
+
|
110
|
+
Note that Markdown formatting syntax is not processed within block-level
|
111
|
+
HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
|
112
|
+
HTML block.
|
113
|
+
|
114
|
+
Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
|
115
|
+
used anywhere in a Markdown paragraph, list item, or header. If you
|
116
|
+
want, you can even use HTML tags instead of Markdown formatting; e.g. if
|
117
|
+
you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
|
118
|
+
link or image syntax, go right ahead.
|
119
|
+
|
120
|
+
Unlike block-level HTML tags, Markdown syntax *is* processed within
|
121
|
+
span-level tags.
|
122
|
+
|
123
|
+
|
124
|
+
<h3 id="autoescape">Automatic Escaping for Special Characters</h3>
|
125
|
+
|
126
|
+
In HTML, there are two characters that demand special treatment: `<`
|
127
|
+
and `&`. Left angle brackets are used to start tags; ampersands are
|
128
|
+
used to denote HTML entities. If you want to use them as literal
|
129
|
+
characters, you must escape them as entities, e.g. `<`, and
|
130
|
+
`&`.
|
131
|
+
|
132
|
+
Ampersands in particular are bedeviling for web writers. If you want to
|
133
|
+
write about 'AT&T', you need to write '`AT&T`'. You even need to
|
134
|
+
escape ampersands within URLs. Thus, if you want to link to:
|
135
|
+
|
136
|
+
http://images.google.com/images?num=30&q=larry+bird
|
137
|
+
|
138
|
+
you need to encode the URL as:
|
139
|
+
|
140
|
+
http://images.google.com/images?num=30&q=larry+bird
|
141
|
+
|
142
|
+
in your anchor tag `href` attribute. Needless to say, this is easy to
|
143
|
+
forget, and is probably the single most common source of HTML validation
|
144
|
+
errors in otherwise well-marked-up web sites.
|
145
|
+
|
146
|
+
Markdown allows you to use these characters naturally, taking care of
|
147
|
+
all the necessary escaping for you. If you use an ampersand as part of
|
148
|
+
an HTML entity, it remains unchanged; otherwise it will be translated
|
149
|
+
into `&`.
|
150
|
+
|
151
|
+
So, if you want to include a copyright symbol in your article, you can write:
|
152
|
+
|
153
|
+
©
|
154
|
+
|
155
|
+
and Markdown will leave it alone. But if you write:
|
156
|
+
|
157
|
+
AT&T
|
158
|
+
|
159
|
+
Markdown will translate it to:
|
160
|
+
|
161
|
+
AT&T
|
162
|
+
|
163
|
+
Similarly, because Markdown supports [inline HTML](#html), if you use
|
164
|
+
angle brackets as delimiters for HTML tags, Markdown will treat them as
|
165
|
+
such. But if you write:
|
166
|
+
|
167
|
+
4 < 5
|
168
|
+
|
169
|
+
Markdown will translate it to:
|
170
|
+
|
171
|
+
4 < 5
|
172
|
+
|
173
|
+
However, inside Markdown code spans and blocks, angle brackets and
|
174
|
+
ampersands are *always* encoded automatically. This makes it easy to use
|
175
|
+
Markdown to write about HTML code. (As opposed to raw HTML, which is a
|
176
|
+
terrible format for writing about HTML syntax, because every single `<`
|
177
|
+
and `&` in your example code needs to be escaped.)
|
178
|
+
|
179
|
+
|
180
|
+
* * *
|
181
|
+
|
182
|
+
|
183
|
+
<h2 id="block">Block Elements</h2>
|
184
|
+
|
185
|
+
|
186
|
+
<h3 id="p">Paragraphs and Line Breaks</h3>
|
187
|
+
|
188
|
+
A paragraph is simply one or more consecutive lines of text, separated
|
189
|
+
by one or more blank lines. (A blank line is any line that looks like a
|
190
|
+
blank line -- a line containing nothing but spaces or tabs is considered
|
191
|
+
blank.) Normal paragraphs should not be indented with spaces or tabs.
|
192
|
+
|
193
|
+
The implication of the "one or more consecutive lines of text" rule is
|
194
|
+
that Markdown supports "hard-wrapped" text paragraphs. This differs
|
195
|
+
significantly from most other text-to-HTML formatters (including Movable
|
196
|
+
Type's "Convert Line Breaks" option) which translate every line break
|
197
|
+
character in a paragraph into a `<br />` tag.
|
198
|
+
|
199
|
+
When you *do* want to insert a `<br />` break tag using Markdown, you
|
200
|
+
end a line with two or more spaces, then type return.
|
201
|
+
|
202
|
+
Yes, this takes a tad more effort to create a `<br />`, but a simplistic
|
203
|
+
"every line break is a `<br />`" rule wouldn't work for Markdown.
|
204
|
+
Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
|
205
|
+
work best -- and look better -- when you format them with hard breaks.
|
206
|
+
|
207
|
+
[bq]: #blockquote
|
208
|
+
[l]: #list
|
209
|
+
|
210
|
+
|
211
|
+
|
212
|
+
<h3 id="header">Headers</h3>
|
213
|
+
|
214
|
+
Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
|
215
|
+
|
216
|
+
Setext-style headers are "underlined" using equal signs (for first-level
|
217
|
+
headers) and dashes (for second-level headers). For example:
|
218
|
+
|
219
|
+
This is an H1
|
220
|
+
=============
|
221
|
+
|
222
|
+
This is an H2
|
223
|
+
-------------
|
224
|
+
|
225
|
+
Any number of underlining `=`'s or `-`'s will work.
|
226
|
+
|
227
|
+
Atx-style headers use 1-6 hash characters at the start of the line,
|
228
|
+
corresponding to header levels 1-6. For example:
|
229
|
+
|
230
|
+
# This is an H1
|
231
|
+
|
232
|
+
## This is an H2
|
233
|
+
|
234
|
+
###### This is an H6
|
235
|
+
|
236
|
+
Optionally, you may "close" atx-style headers. This is purely
|
237
|
+
cosmetic -- you can use this if you think it looks better. The
|
238
|
+
closing hashes don't even need to match the number of hashes
|
239
|
+
used to open the header. (The number of opening hashes
|
240
|
+
determines the header level.) :
|
241
|
+
|
242
|
+
# This is an H1 #
|
243
|
+
|
244
|
+
## This is an H2 ##
|
245
|
+
|
246
|
+
### This is an H3 ######
|
247
|
+
|
248
|
+
|
249
|
+
<h3 id="blockquote">Blockquotes</h3>
|
250
|
+
|
251
|
+
Markdown uses email-style `>` characters for blockquoting. If you're
|
252
|
+
familiar with quoting passages of text in an email message, then you
|
253
|
+
know how to create a blockquote in Markdown. It looks best if you hard
|
254
|
+
wrap the text and put a `>` before every line:
|
255
|
+
|
256
|
+
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
257
|
+
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
258
|
+
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
259
|
+
>
|
260
|
+
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
261
|
+
> id sem consectetuer libero luctus adipiscing.
|
262
|
+
|
263
|
+
Markdown allows you to be lazy and only put the `>` before the first
|
264
|
+
line of a hard-wrapped paragraph:
|
265
|
+
|
266
|
+
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
|
267
|
+
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
268
|
+
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
269
|
+
|
270
|
+
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
271
|
+
id sem consectetuer libero luctus adipiscing.
|
272
|
+
|
273
|
+
Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
|
274
|
+
adding additional levels of `>`:
|
275
|
+
|
276
|
+
> This is the first level of quoting.
|
277
|
+
>
|
278
|
+
> > This is nested blockquote.
|
279
|
+
>
|
280
|
+
> Back to the first level.
|
281
|
+
|
282
|
+
Blockquotes can contain other Markdown elements, including headers, lists,
|
283
|
+
and code blocks:
|
284
|
+
|
285
|
+
> ## This is a header.
|
286
|
+
>
|
287
|
+
> 1. This is the first list item.
|
288
|
+
> 2. This is the second list item.
|
289
|
+
>
|
290
|
+
> Here's some example code:
|
291
|
+
>
|
292
|
+
> return shell_exec("echo $input | $markdown_script");
|
293
|
+
|
294
|
+
Any decent text editor should make email-style quoting easy. For
|
295
|
+
example, with BBEdit, you can make a selection and choose Increase
|
296
|
+
Quote Level from the Text menu.
|
297
|
+
|
298
|
+
|
299
|
+
<h3 id="list">Lists</h3>
|
300
|
+
|
301
|
+
Markdown supports ordered (numbered) and unordered (bulleted) lists.
|
302
|
+
|
303
|
+
Unordered lists use asterisks, pluses, and hyphens -- interchangably
|
304
|
+
-- as list markers:
|
305
|
+
|
306
|
+
* Red
|
307
|
+
* Green
|
308
|
+
* Blue
|
309
|
+
|
310
|
+
is equivalent to:
|
311
|
+
|
312
|
+
+ Red
|
313
|
+
+ Green
|
314
|
+
+ Blue
|
315
|
+
|
316
|
+
and:
|
317
|
+
|
318
|
+
- Red
|
319
|
+
- Green
|
320
|
+
- Blue
|
321
|
+
|
322
|
+
Ordered lists use numbers followed by periods:
|
323
|
+
|
324
|
+
1. Bird
|
325
|
+
2. McHale
|
326
|
+
3. Parish
|
327
|
+
|
328
|
+
It's important to note that the actual numbers you use to mark the
|
329
|
+
list have no effect on the HTML output Markdown produces. The HTML
|
330
|
+
Markdown produces from the above list is:
|
331
|
+
|
332
|
+
<ol>
|
333
|
+
<li>Bird</li>
|
334
|
+
<li>McHale</li>
|
335
|
+
<li>Parish</li>
|
336
|
+
</ol>
|
337
|
+
|
338
|
+
If you instead wrote the list in Markdown like this:
|
339
|
+
|
340
|
+
1. Bird
|
341
|
+
1. McHale
|
342
|
+
1. Parish
|
343
|
+
|
344
|
+
or even:
|
345
|
+
|
346
|
+
3. Bird
|
347
|
+
1. McHale
|
348
|
+
8. Parish
|
349
|
+
|
350
|
+
you'd get the exact same HTML output. The point is, if you want to,
|
351
|
+
you can use ordinal numbers in your ordered Markdown lists, so that
|
352
|
+
the numbers in your source match the numbers in your published HTML.
|
353
|
+
But if you want to be lazy, you don't have to.
|
354
|
+
|
355
|
+
If you do use lazy list numbering, however, you should still start the
|
356
|
+
list with the number 1. At some point in the future, Markdown may support
|
357
|
+
starting ordered lists at an arbitrary number.
|
358
|
+
|
359
|
+
List markers typically start at the left margin, but may be indented by
|
360
|
+
up to three spaces. List markers must be followed by one or more spaces
|
361
|
+
or a tab.
|
362
|
+
|
363
|
+
To make lists look nice, you can wrap items with hanging indents:
|
364
|
+
|
365
|
+
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
366
|
+
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
367
|
+
viverra nec, fringilla in, laoreet vitae, risus.
|
368
|
+
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
369
|
+
Suspendisse id sem consectetuer libero luctus adipiscing.
|
370
|
+
|
371
|
+
But if you want to be lazy, you don't have to:
|
372
|
+
|
373
|
+
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
|
374
|
+
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
375
|
+
viverra nec, fringilla in, laoreet vitae, risus.
|
376
|
+
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
377
|
+
Suspendisse id sem consectetuer libero luctus adipiscing.
|
378
|
+
|
379
|
+
If list items are separated by blank lines, Markdown will wrap the
|
380
|
+
items in `<p>` tags in the HTML output. For example, this input:
|
381
|
+
|
382
|
+
* Bird
|
383
|
+
* Magic
|
384
|
+
|
385
|
+
will turn into:
|
386
|
+
|
387
|
+
<ul>
|
388
|
+
<li>Bird</li>
|
389
|
+
<li>Magic</li>
|
390
|
+
</ul>
|
391
|
+
|
392
|
+
But this:
|
393
|
+
|
394
|
+
* Bird
|
395
|
+
|
396
|
+
* Magic
|
397
|
+
|
398
|
+
will turn into:
|
399
|
+
|
400
|
+
<ul>
|
401
|
+
<li><p>Bird</p></li>
|
402
|
+
<li><p>Magic</p></li>
|
403
|
+
</ul>
|
404
|
+
|
405
|
+
List items may consist of multiple paragraphs. Each subsequent
|
406
|
+
paragraph in a list item must be intended by either 4 spaces
|
407
|
+
or one tab:
|
408
|
+
|
409
|
+
1. This is a list item with two paragraphs. Lorem ipsum dolor
|
410
|
+
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
|
411
|
+
mi posuere lectus.
|
412
|
+
|
413
|
+
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
|
414
|
+
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
|
415
|
+
sit amet velit.
|
416
|
+
|
417
|
+
2. Suspendisse id sem consectetuer libero luctus adipiscing.
|
418
|
+
|
419
|
+
It looks nice if you indent every line of the subsequent
|
420
|
+
paragraphs, but here again, Markdown will allow you to be
|
421
|
+
lazy:
|
422
|
+
|
423
|
+
* This is a list item with two paragraphs.
|
424
|
+
|
425
|
+
This is the second paragraph in the list item. You're
|
426
|
+
only required to indent the first line. Lorem ipsum dolor
|
427
|
+
sit amet, consectetuer adipiscing elit.
|
428
|
+
|
429
|
+
* Another item in the same list.
|
430
|
+
|
431
|
+
To put a blockquote within a list item, the blockquote's `>`
|
432
|
+
delimiters need to be indented:
|
433
|
+
|
434
|
+
* A list item with a blockquote:
|
435
|
+
|
436
|
+
> This is a blockquote
|
437
|
+
> inside a list item.
|
438
|
+
|
439
|
+
To put a code block within a list item, the code block needs
|
440
|
+
to be indented *twice* -- 8 spaces or two tabs:
|
441
|
+
|
442
|
+
* A list item with a code block:
|
443
|
+
|
444
|
+
<code goes here>
|
445
|
+
|
446
|
+
|
447
|
+
It's worth noting that it's possible to trigger an ordered list by
|
448
|
+
accident, by writing something like this:
|
449
|
+
|
450
|
+
1986. What a great season.
|
451
|
+
|
452
|
+
In other words, a *number-period-space* sequence at the beginning of a
|
453
|
+
line. To avoid this, you can backslash-escape the period:
|
454
|
+
|
455
|
+
1986\. What a great season.
|
456
|
+
|
457
|
+
|
458
|
+
|
459
|
+
<h3 id="precode">Code Blocks</h3>
|
460
|
+
|
461
|
+
Pre-formatted code blocks are used for writing about programming or
|
462
|
+
markup source code. Rather than forming normal paragraphs, the lines
|
463
|
+
of a code block are interpreted literally. Markdown wraps a code block
|
464
|
+
in both `<pre>` and `<code>` tags.
|
465
|
+
|
466
|
+
To produce a code block in Markdown, simply indent every line of the
|
467
|
+
block by at least 4 spaces or 1 tab. For example, given this input:
|
468
|
+
|
469
|
+
This is a normal paragraph:
|
470
|
+
|
471
|
+
This is a code block.
|
472
|
+
|
473
|
+
Markdown will generate:
|
474
|
+
|
475
|
+
<p>This is a normal paragraph:</p>
|
476
|
+
|
477
|
+
<pre><code>This is a code block.
|
478
|
+
</code></pre>
|
479
|
+
|
480
|
+
One level of indentation -- 4 spaces or 1 tab -- is removed from each
|
481
|
+
line of the code block. For example, this:
|
482
|
+
|
483
|
+
Here is an example of AppleScript:
|
484
|
+
|
485
|
+
tell application "Foo"
|
486
|
+
beep
|
487
|
+
end tell
|
488
|
+
|
489
|
+
will turn into:
|
490
|
+
|
491
|
+
<p>Here is an example of AppleScript:</p>
|
492
|
+
|
493
|
+
<pre><code>tell application "Foo"
|
494
|
+
beep
|
495
|
+
end tell
|
496
|
+
</code></pre>
|
497
|
+
|
498
|
+
A code block continues until it reaches a line that is not indented
|
499
|
+
(or the end of the article).
|
500
|
+
|
501
|
+
Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
|
502
|
+
are automatically converted into HTML entities. This makes it very
|
503
|
+
easy to include example HTML source code using Markdown -- just paste
|
504
|
+
it and indent it, and Markdown will handle the hassle of encoding the
|
505
|
+
ampersands and angle brackets. For example, this:
|
506
|
+
|
507
|
+
<div class="footer">
|
508
|
+
© 2004 Foo Corporation
|
509
|
+
</div>
|
510
|
+
|
511
|
+
will turn into:
|
512
|
+
|
513
|
+
<pre><code><div class="footer">
|
514
|
+
&copy; 2004 Foo Corporation
|
515
|
+
</div>
|
516
|
+
</code></pre>
|
517
|
+
|
518
|
+
Regular Markdown syntax is not processed within code blocks. E.g.,
|
519
|
+
asterisks are just literal asterisks within a code block. This means
|
520
|
+
it's also easy to use Markdown to write about Markdown's own syntax.
|
521
|
+
|
522
|
+
|
523
|
+
|
524
|
+
<h3 id="hr">Horizontal Rules</h3>
|
525
|
+
|
526
|
+
You can produce a horizontal rule tag (`<hr />`) by placing three or
|
527
|
+
more hyphens, asterisks, or underscores on a line by themselves. If you
|
528
|
+
wish, you may use spaces between the hyphens or asterisks. Each of the
|
529
|
+
following lines will produce a horizontal rule:
|
530
|
+
|
531
|
+
* * *
|
532
|
+
|
533
|
+
***
|
534
|
+
|
535
|
+
*****
|
536
|
+
|
537
|
+
- - -
|
538
|
+
|
539
|
+
---------------------------------------
|
540
|
+
|
541
|
+
|
542
|
+
* * *
|
543
|
+
|
544
|
+
<h2 id="span">Span Elements</h2>
|
545
|
+
|
546
|
+
<h3 id="link">Links</h3>
|
547
|
+
|
548
|
+
Markdown supports two style of links: *inline* and *reference*.
|
549
|
+
|
550
|
+
In both styles, the link text is delimited by [square brackets].
|
551
|
+
|
552
|
+
To create an inline link, use a set of regular parentheses immediately
|
553
|
+
after the link text's closing square bracket. Inside the parentheses,
|
554
|
+
put the URL where you want the link to point, along with an *optional*
|
555
|
+
title for the link, surrounded in quotes. For example:
|
556
|
+
|
557
|
+
This is [an example](http://example.com/ "Title") inline link.
|
558
|
+
|
559
|
+
[This link](http://example.net/) has no title attribute.
|
560
|
+
|
561
|
+
Will produce:
|
562
|
+
|
563
|
+
<p>This is <a href="http://example.com/" title="Title">
|
564
|
+
an example</a> inline link.</p>
|
565
|
+
|
566
|
+
<p><a href="http://example.net/">This link</a> has no
|
567
|
+
title attribute.</p>
|
568
|
+
|
569
|
+
If you're referring to a local resource on the same server, you can
|
570
|
+
use relative paths:
|
571
|
+
|
572
|
+
See my [About](/about/) page for details.
|
573
|
+
|
574
|
+
Reference-style links use a second set of square brackets, inside
|
575
|
+
which you place a label of your choosing to identify the link:
|
576
|
+
|
577
|
+
This is [an example][id] reference-style link.
|
578
|
+
|
579
|
+
You can optionally use a space to separate the sets of brackets:
|
580
|
+
|
581
|
+
This is [an example] [id] reference-style link.
|
582
|
+
|
583
|
+
Then, anywhere in the document, you define your link label like this,
|
584
|
+
on a line by itself:
|
585
|
+
|
586
|
+
[id]: http://example.com/ "Optional Title Here"
|
587
|
+
|
588
|
+
That is:
|
589
|
+
|
590
|
+
* Square brackets containing the link identifier (optionally
|
591
|
+
indented from the left margin using up to three spaces);
|
592
|
+
* followed by a colon;
|
593
|
+
* followed by one or more spaces (or tabs);
|
594
|
+
* followed by the URL for the link;
|
595
|
+
* optionally followed by a title attribute for the link, enclosed
|
596
|
+
in double or single quotes, or enclosed in parentheses.
|
597
|
+
|
598
|
+
The following three link definitions are equivalent:
|
599
|
+
|
600
|
+
[foo]: http://example.com/ "Optional Title Here"
|
601
|
+
[foo]: http://example.com/ 'Optional Title Here'
|
602
|
+
[foo]: http://example.com/ (Optional Title Here)
|
603
|
+
|
604
|
+
**Note:** There is a known bug in Markdown.pl 1.0.1 which prevents
|
605
|
+
single quotes from being used to delimit link titles.
|
606
|
+
|
607
|
+
The link URL may, optionally, be surrounded by angle brackets:
|
608
|
+
|
609
|
+
[id]: <http://example.com/> "Optional Title Here"
|
610
|
+
|
611
|
+
You can put the title attribute on the next line and use extra spaces
|
612
|
+
or tabs for padding, which tends to look better with longer URLs:
|
613
|
+
|
614
|
+
[id]: http://example.com/longish/path/to/resource/here
|
615
|
+
"Optional Title Here"
|
616
|
+
|
617
|
+
Link definitions are only used for creating links during Markdown
|
618
|
+
processing, and are stripped from your document in the HTML output.
|
619
|
+
|
620
|
+
Link definition names may constist of letters, numbers, spaces, and
|
621
|
+
punctuation -- but they are *not* case sensitive. E.g. these two
|
622
|
+
links:
|
623
|
+
|
624
|
+
[link text][a]
|
625
|
+
[link text][A]
|
626
|
+
|
627
|
+
are equivalent.
|
628
|
+
|
629
|
+
The *implicit link name* shortcut allows you to omit the name of the
|
630
|
+
link, in which case the link text itself is used as the name.
|
631
|
+
Just use an empty set of square brackets -- e.g., to link the word
|
632
|
+
"Google" to the google.com web site, you could simply write:
|
633
|
+
|
634
|
+
[Google][]
|
635
|
+
|
636
|
+
And then define the link:
|
637
|
+
|
638
|
+
[Google]: http://google.com/
|
639
|
+
|
640
|
+
Because link names may contain spaces, this shortcut even works for
|
641
|
+
multiple words in the link text:
|
642
|
+
|
643
|
+
Visit [Daring Fireball][] for more information.
|
644
|
+
|
645
|
+
And then define the link:
|
646
|
+
|
647
|
+
[Daring Fireball]: http://daringfireball.net/
|
648
|
+
|
649
|
+
Link definitions can be placed anywhere in your Markdown document. I
|
650
|
+
tend to put them immediately after each paragraph in which they're
|
651
|
+
used, but if you want, you can put them all at the end of your
|
652
|
+
document, sort of like footnotes.
|
653
|
+
|
654
|
+
Here's an example of reference links in action:
|
655
|
+
|
656
|
+
I get 10 times more traffic from [Google] [1] than from
|
657
|
+
[Yahoo] [2] or [MSN] [3].
|
658
|
+
|
659
|
+
[1]: http://google.com/ "Google"
|
660
|
+
[2]: http://search.yahoo.com/ "Yahoo Search"
|
661
|
+
[3]: http://search.msn.com/ "MSN Search"
|
662
|
+
|
663
|
+
Using the implicit link name shortcut, you could instead write:
|
664
|
+
|
665
|
+
I get 10 times more traffic from [Google][] than from
|
666
|
+
[Yahoo][] or [MSN][].
|
667
|
+
|
668
|
+
[google]: http://google.com/ "Google"
|
669
|
+
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
|
670
|
+
[msn]: http://search.msn.com/ "MSN Search"
|
671
|
+
|
672
|
+
Both of the above examples will produce the following HTML output:
|
673
|
+
|
674
|
+
<p>I get 10 times more traffic from <a href="http://google.com/"
|
675
|
+
title="Google">Google</a> than from
|
676
|
+
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
|
677
|
+
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
|
678
|
+
|
679
|
+
For comparison, here is the same paragraph written using
|
680
|
+
Markdown's inline link style:
|
681
|
+
|
682
|
+
I get 10 times more traffic from [Google](http://google.com/ "Google")
|
683
|
+
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
|
684
|
+
[MSN](http://search.msn.com/ "MSN Search").
|
685
|
+
|
686
|
+
The point of reference-style links is not that they're easier to
|
687
|
+
write. The point is that with reference-style links, your document
|
688
|
+
source is vastly more readable. Compare the above examples: using
|
689
|
+
reference-style links, the paragraph itself is only 81 characters
|
690
|
+
long; with inline-style links, it's 176 characters; and as raw HTML,
|
691
|
+
it's 234 characters. In the raw HTML, there's more markup than there
|
692
|
+
is text.
|
693
|
+
|
694
|
+
With Markdown's reference-style links, a source document much more
|
695
|
+
closely resembles the final output, as rendered in a browser. By
|
696
|
+
allowing you to move the markup-related metadata out of the paragraph,
|
697
|
+
you can add links without interrupting the narrative flow of your
|
698
|
+
prose.
|
699
|
+
|
700
|
+
|
701
|
+
<h3 id="em">Emphasis</h3>
|
702
|
+
|
703
|
+
Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
|
704
|
+
emphasis. Text wrapped with one `*` or `_` will be wrapped with an
|
705
|
+
HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
|
706
|
+
`<strong>` tag. E.g., this input:
|
707
|
+
|
708
|
+
*single asterisks*
|
709
|
+
|
710
|
+
_single underscores_
|
711
|
+
|
712
|
+
**double asterisks**
|
713
|
+
|
714
|
+
__double underscores__
|
715
|
+
|
716
|
+
will produce:
|
717
|
+
|
718
|
+
<em>single asterisks</em>
|
719
|
+
|
720
|
+
<em>single underscores</em>
|
721
|
+
|
722
|
+
<strong>double asterisks</strong>
|
723
|
+
|
724
|
+
<strong>double underscores</strong>
|
725
|
+
|
726
|
+
You can use whichever style you prefer; the lone restriction is that
|
727
|
+
the same character must be used to open and close an emphasis span.
|
728
|
+
|
729
|
+
Emphasis can be used in the middle of a word:
|
730
|
+
|
731
|
+
un*fucking*believable
|
732
|
+
|
733
|
+
But if you surround an `*` or `_` with spaces, it'll be treated as a
|
734
|
+
literal asterisk or underscore.
|
735
|
+
|
736
|
+
To produce a literal asterisk or underscore at a position where it
|
737
|
+
would otherwise be used as an emphasis delimiter, you can backslash
|
738
|
+
escape it:
|
739
|
+
|
740
|
+
\*this text is surrounded by literal asterisks\*
|
741
|
+
|
742
|
+
|
743
|
+
|
744
|
+
<h3 id="code">Code</h3>
|
745
|
+
|
746
|
+
To indicate a span of code, wrap it with backtick quotes (`` ` ``).
|
747
|
+
Unlike a pre-formatted code block, a code span indicates code within a
|
748
|
+
normal paragraph. For example:
|
749
|
+
|
750
|
+
Use the `printf()` function.
|
751
|
+
|
752
|
+
will produce:
|
753
|
+
|
754
|
+
<p>Use the <code>printf()</code> function.</p>
|
755
|
+
|
756
|
+
To include a literal backtick character within a code span, you can use
|
757
|
+
multiple backticks as the opening and closing delimiters:
|
758
|
+
|
759
|
+
``There is a literal backtick (`) here.``
|
760
|
+
|
761
|
+
which will produce this:
|
762
|
+
|
763
|
+
<p><code>There is a literal backtick (`) here.</code></p>
|
764
|
+
|
765
|
+
The backtick delimiters surrounding a code span may include spaces --
|
766
|
+
one after the opening, one before the closing. This allows you to place
|
767
|
+
literal backtick characters at the beginning or end of a code span:
|
768
|
+
|
769
|
+
A single backtick in a code span: `` ` ``
|
770
|
+
|
771
|
+
A backtick-delimited string in a code span: `` `foo` ``
|
772
|
+
|
773
|
+
will produce:
|
774
|
+
|
775
|
+
<p>A single backtick in a code span: <code>`</code></p>
|
776
|
+
|
777
|
+
<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
|
778
|
+
|
779
|
+
With a code span, ampersands and angle brackets are encoded as HTML
|
780
|
+
entities automatically, which makes it easy to include example HTML
|
781
|
+
tags. Markdown will turn this:
|
782
|
+
|
783
|
+
Please don't use any `<blink>` tags.
|
784
|
+
|
785
|
+
into:
|
786
|
+
|
787
|
+
<p>Please don't use any <code><blink></code> tags.</p>
|
788
|
+
|
789
|
+
You can write this:
|
790
|
+
|
791
|
+
`—` is the decimal-encoded equivalent of `—`.
|
792
|
+
|
793
|
+
to produce:
|
794
|
+
|
795
|
+
<p><code>&#8212;</code> is the decimal-encoded
|
796
|
+
equivalent of <code>&mdash;</code>.</p>
|
797
|
+
|
798
|
+
|
799
|
+
|
800
|
+
<h3 id="img">Images</h3>
|
801
|
+
|
802
|
+
Admittedly, it's fairly difficult to devise a "natural" syntax for
|
803
|
+
placing images into a plain text document format.
|
804
|
+
|
805
|
+
Markdown uses an image syntax that is intended to resemble the syntax
|
806
|
+
for links, allowing for two styles: *inline* and *reference*.
|
807
|
+
|
808
|
+
Inline image syntax looks like this:
|
809
|
+
|
810
|
+
![Alt text](/path/to/img.jpg)
|
811
|
+
|
812
|
+
![Alt text](/path/to/img.jpg "Optional title")
|
813
|
+
|
814
|
+
That is:
|
815
|
+
|
816
|
+
* An exclamation mark: `!`;
|
817
|
+
* followed by a set of square brackets, containing the `alt`
|
818
|
+
attribute text for the image;
|
819
|
+
* followed by a set of parentheses, containing the URL or path to
|
820
|
+
the image, and an optional `title` attribute enclosed in double
|
821
|
+
or single quotes.
|
822
|
+
|
823
|
+
Reference-style image syntax looks like this:
|
824
|
+
|
825
|
+
![Alt text][id]
|
826
|
+
|
827
|
+
Where "id" is the name of a defined image reference. Image references
|
828
|
+
are defined using syntax identical to link references:
|
829
|
+
|
830
|
+
[id]: url/to/image "Optional title attribute"
|
831
|
+
|
832
|
+
As of this writing, Markdown has no syntax for specifying the
|
833
|
+
dimensions of an image; if this is important to you, you can simply
|
834
|
+
use regular HTML `<img>` tags.
|
835
|
+
|
836
|
+
|
837
|
+
* * *
|
838
|
+
|
839
|
+
|
840
|
+
<h2 id="misc">Miscellaneous</h2>
|
841
|
+
|
842
|
+
<h3 id="autolink">Automatic Links</h3>
|
843
|
+
|
844
|
+
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:
|
845
|
+
|
846
|
+
<http://example.com/>
|
847
|
+
|
848
|
+
Markdown will turn this into:
|
849
|
+
|
850
|
+
<a href="http://example.com/">http://example.com/</a>
|
851
|
+
|
852
|
+
Automatic links for email addresses work similarly, except that
|
853
|
+
Markdown will also perform a bit of randomized decimal and hex
|
854
|
+
entity-encoding to help obscure your address from address-harvesting
|
855
|
+
spambots. For example, Markdown will turn this:
|
856
|
+
|
857
|
+
<address@example.com>
|
858
|
+
|
859
|
+
into something like this:
|
860
|
+
|
861
|
+
<a href="mailto:addre
|
862
|
+
ss@example.co
|
863
|
+
m">address@exa
|
864
|
+
mple.com</a>
|
865
|
+
|
866
|
+
which will render in a browser as a clickable link to "address@example.com".
|
867
|
+
|
868
|
+
(This sort of entity-encoding trick will indeed fool many, if not
|
869
|
+
most, address-harvesting bots, but it definitely won't fool all of
|
870
|
+
them. It's better than nothing, but an address published in this way
|
871
|
+
will probably eventually start receiving spam.)
|
872
|
+
|
873
|
+
|
874
|
+
|
875
|
+
<h3 id="backslash">Backslash Escapes</h3>
|
876
|
+
|
877
|
+
Markdown allows you to use backslash escapes to generate literal
|
878
|
+
characters which would otherwise have special meaning in Markdown's
|
879
|
+
formatting syntax. For example, if you wanted to surround a word with
|
880
|
+
literal asterisks (instead of an HTML `<em>` tag), you can backslashes
|
881
|
+
before the asterisks, like this:
|
882
|
+
|
883
|
+
\*literal asterisks\*
|
884
|
+
|
885
|
+
Markdown provides backslash escapes for the following characters:
|
886
|
+
|
887
|
+
\ backslash
|
888
|
+
` backtick
|
889
|
+
* asterisk
|
890
|
+
_ underscore
|
891
|
+
{} curly braces
|
892
|
+
[] square brackets
|
893
|
+
() parentheses
|
894
|
+
# hash mark
|
895
|
+
+ plus sign
|
896
|
+
- minus sign (hyphen)
|
897
|
+
. dot
|
898
|
+
! exclamation mark
|
899
|
+
|