]> git.wincent.com - wikitext.git/blob - README.rdoc
Split String#wikitext_preprocess into a separate file
[wikitext.git] / README.rdoc
1 The Wikitext extension is a fast wikitext-to-HTML translator written
2 in C and packaged as a Ruby extension.
3
4 Usage is straightforward:
5
6  $ irb -r wikitext
7  >> Wikitext::Parser.new.parse("hello world!")
8  => "<p>hello world!</p>\n"
9
10 = Design goals
11
12 I needed a wikitext-to-HTML translator for a Rails application; a number
13 of design goals flowed on from this:
14
15 * _fast_: Rails has a reputation for being slow, so the translator had
16   to be part of the solution, not part of the problem
17 * _efficient_: again, given how much memory Rails likes to use, the
18   translator had to be very memory-efficient
19 * _robust_: on a public-facing web application that had to be up for long
20   periods, the translator had to be stable (no crashes, no resource leaks)
21 * _secure_: again, accepting input from untrusted sources meant that the
22   translator had to sanitize or reject unsafe input
23 * <em>easy to use</em>: for end users, the translator should provide a
24   simple, familiar markup as close as possible to what they already know
25   from other applications (such as MediaWiki, the wiki software that
26   powers Wikipedia)
27 * _forgiving_: wikitext is presentation markup, not source code, so the
28   translator should do a reasonable job of formatting even the most
29   invalid markup rather than giving up
30 * _informative_: when provided invalid markup the translator should
31   fail gracefully and emit HTML that provides useful visual feedback
32   about where the errors are in the input
33 * <em>multilingual-friendly</em>: the translator should handle input beyond
34   printable ASCII in a compatible fashion
35 * _attractive_: the emitted HTML source should be consistent and attractive
36 * <em>valid output</em>: regardless of the input, the translator should
37   always produce valid HTML5 output
38 * <em>well-tested</em>: the translator should have a comprehensive test
39   suite to ensure that its behaviour is not only correct but also stable
40   over time
41 * <em>cross-platform</em>: should work identically on Mac OS X, Linux
42   (explicitly tested platforms) and perhaps others as well
43
44 Some notable things that were _not_ design goals:
45
46 * implement _all_ of the MediaWiki syntax (tables etc)
47
48 = Markup
49
50 The markup is very close to that used by MediaWiki, the most popular wiki
51 software and the one that powers Wikipedia.
52
53 == Headings
54
55  = Heading 1 =
56  == Heading 2 ==
57  === Heading 3 ===
58  ==== Heading 4 ====
59  ===== Heading 5 =====
60  ====== Heading 6 ======
61
62 Are marked up as:
63
64  <h1>Heading 1</h1>
65  <h2>Heading 2</h2>
66  <h3>Heading 3</h3>
67  <h4>Heading 4</h4>
68  <h5>Heading 5</h5>
69  <h6>Heading 6</h6>
70
71 == Paragraphs
72
73 Consecutive linebreaks are converted into paragraph breaks.
74
75  This is one paragraph.
76  Another line.
77  
78  And this is another.
79
80 Would be marked up as:
81
82  <p>This is one paragraph. Another line.</p>
83  <p>And this is another.</p>
84
85 == Emphasis, Strong
86
87 Emphasis is marked up as follows:
88
89   ''emphasized''
90
91 Which gets translated into:
92
93   <em>emphasized</em>
94
95 Strong is marked up like this:
96
97   '''strong text'''
98
99 And transformed into:
100
101   <strong>strong text</strong>
102
103 You can nest spans inside one another, provided you don't try to produce
104 invalid HTML (for example, nesting strong inside strong). Here is a valid
105 example:
106
107   '''''foo'' bar''' baz
108
109 This would become:
110
111   <strong><em>foo</em> bar</strong> baz
112
113 Note that the translator emits HTML on the fly, so when it sees the
114 first run of five apostrophes it has no way of knowing what will come
115 afterwards and so doesn't know whether you mean to say "strong em" or
116 "em strong"; it therefore always assumes "strong em". If you wish to
117 force the alternative interpretation you can do one of the following:
118
119  '' '''foo''' bar'' baz (ie. use whitespace)
120  ''<nowiki></nowiki>'''foo''' bar'' baz (ie. insert an empty nowiki span)
121  <em><strong>foo</strong> bar</em> baz (ie. use explicit HTML tags instead)
122  <em>'''foo''' bar</em> baz (ie. use explicit HTML tags instead)
123
124 Note that to avoid ambiguity, the translator will not let you intermix
125 the shorthand style with the literal HTML tag style.
126
127  <em>foo'' (ie. intermixed, invalid)
128
129 == Teletype
130
131 The translator recognizes both standard HTML +tt+ tags and the
132 backtick (`) as a shorthand. These two are equivalent:
133
134   <tt>fixed</tt>
135   `fixed`
136
137 As of version 2.0, this markup is actually translated to +code+ tags
138 in the output because the +tt+ tag was removed from the HTML5 standard.
139
140 If you need to insert a literal backtick in your text you use a +nowiki+
141 span:
142
143   here follows a literal <nowiki>`</nowiki> backtick
144
145 To avoid ambiguity, the translator will not let you intermix the two
146 styles.
147
148 == +nowiki+ spans
149
150 Already mentioned above, you can use +nowiki+ tags to temporarily disable
151 wikitext markup. As soon as the translator sees the opening +nowiki+ tag
152 it starts emitting a literal copy of everything it sees up until the
153 closing +nowiki+ tag:
154
155   Hello <nowiki>''world''</nowiki>
156
157 Would be emitted as:
158
159   Hello ''world''
160
161 == Blockquotes
162
163   > Hello world!
164   > Bye for now.
165
166 Would be emitted as:
167
168   <blockquote><p>Hello world! Bye for now.</p></blockquote>
169
170 You can nest blockquotes or any other kind of block or span inside
171 blockquotes. For example:
172
173   > first quote
174   >> quote inside a quote
175
176 == Preformatted text
177
178 Any line indented with whitespace will be interpreted as part of a +pre+
179 block. Wikitext markup inside +pre+ blocks has no special meaning. For
180 example, consider the following block indented by a single space:
181
182    // source code listing
183    void foo(void)
184    {
185       x++;
186    }
187
188 Would be translated into:
189
190   <pre>// source code listing
191   void foo(void)
192   {
193     x++;
194   }</pre>
195
196 +pre+ blocks may be nested inside +blockquote+ blocks.
197
198 == Internal links
199
200   [[article title]]
201
202 Would become:
203
204   <a href="/wiki/article_title">article title</a>
205
206 And:
207
208   [[title|link text]]
209
210 Would become:
211
212   <a href="/wiki/article">link text</a>
213
214 See the Parser attributes documentation for how you can override the
215 default link prefix (<em>/wiki/</em> as shown in the example), and how
216 "red links" can be implemented by applying custom CSS depending on the
217 link target (this can be used to make links to non-existent pages appear
218 in a different color).
219
220 == Alternative blockquote and preformatted block syntax
221
222 For +blockquote+ and +pre+ blocks that go on for many lines it may be
223 more convenient to use the alternative syntax which uses standard
224 HTML tags rather than special prefixes at the beginning of each line.
225
226   <blockquote>This is
227   a blockquote!</blockquote>
228   
229   <pre>And this is
230   preformatted text</pre>
231
232 +blockquote+ and +pre+ blocks may nest inside other +blockquote+
233 blocks.
234
235 Note that to avoid ambiguity, the translator will not let you intermix
236 the two styles (HTML markup and wikitext markup).
237
238 +pre+ blocks may also contain a custom +lang+ attribute for the purposes
239 of marking up a block for syntax-highlighting (note that the highlighting
240 itself would be provided by JavaScript in the browser and is not actually
241 part of the Wikitext extension). For example:
242
243   <pre lang="ruby">puts @person.name</pre>
244
245 Would be translated into:
246
247   <pre class="ruby-syntax">puts @person.name</pre>
248
249 The +lang+ attribute may only contain letters, so "Objective-C", for
250 example would need to be written as "objc" or similar.
251
252 == External links
253
254   [http://example.com/ this site]
255
256 Would become:
257
258   <a href="http://example.com/" class="external">this site</a>
259
260 See the Parser attributes documentation for information on overriding
261 the default external link class (+external+ in this example).
262
263 Note that in addition to providing a fully-qualified URL including a
264 protocol (such as "http://" or "ftp://") you also have the option of
265 using an unqualified "path"-style URL. This is useful for making
266 links to other pages still on the same site, but outside of the wiki:
267
268   [/issues/1024 ticket #1024]
269
270 Would become:
271
272   <a href="/issues/1024">ticket #1024</a>
273
274 Note that no "external" class is included in the generated link.
275
276 To avoid false positives, what constitutes a "path" is
277 narrowly-defined as a string that begins with a slash, optionally
278 followed by zero or more "path components" consisting of upper and
279 lowercase letters, numbers, underscores, hyphens or periods. Path
280 components are separated by a slash, and the trailing slash after
281 the last path component is optional.
282
283 == Images
284
285   {{foo.png}}
286
287 Would become:
288
289   <img src="/images/foo.png" alt="foo.png" />
290
291 You can override the "/images/" prefix using the +img_prefix+ attribute
292 of the Parser.
293
294 You can also specify "absolute" image "src" attributes regardless of
295 the current prefix setting by starting the image path with a forward
296 slash; that is:
297
298   {{/foo.png}}
299
300 Would become:
301
302   <img src="/foo.png" alt="/foo.png" />
303
304 = Rails support
305
306 The Wikitext extension provides a template handler so that templates named
307 following the <tt>template_name.html.wikitext</tt> format will automatically be
308 translated from wikitext markup into HTML when rendered.
309
310 Likewise, a +to_wikitext+ method (aliased as +w+) is added to the +String+
311 class (and also +NilClass+, for convenience) so that content can be easily
312 translated.
313
314 Finally, a Wikitext::Parser#shared_parser method is added to provide
315 convenient access to a shared singleton instance of the parser so as to
316 avoid repeatedly instantiating and setting up new parser instances as part
317 of every request.
318
319 == Rails 2.3
320
321 The plug-in can be activated with an appropriate <tt>config.gem</tt> statement
322 in your <tt>config/environment.rb</tt>:
323
324   config.gem 'wikitext'
325
326 == Rails 3.0
327
328 Add a line like the following to your Gemfile:
329
330   gem 'wikitext', '>= 2.0'
331
332 Note that while older versions of Wikitext do work with Rails 3 to some degree,
333 for full compatibility Wikitext version 2.0 or higher should be used.
334
335 At the time of writing, it appears that Rails 3 and Bundler do not
336 automatically call the <tt>rails/init.rb</tt> file any more, so it is necessary
337 to explicitly activate the Rails support (the template handler, +to_wikitext+
338 and +w+ methods, and +shared_parser+ instance) by adding a line like this
339 to a file under <tt>config/initializers</tt>:
340
341   require 'wikitext/rails'
342
343 = Links
344
345 * RubyForge project page: http://rubyforge.org/projects/wikitext
346 * RDoc: http://wikitext.rubyforge.org
347 * Source: http://git.wincent.com/wikitext.git
348 * Author/maintainer: Wincent Colaiuta (win@wincent.com, http://wincent.com)
349
350 = License
351
352 Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
353
354 Redistribution and use in source and binary forms, with or without
355 modification, are permitted provided that the following conditions are met:
356
357 1. Redistributions of source code must retain the above copyright notice,
358    this list of conditions and the following disclaimer.
359 2. Redistributions in binary form must reproduce the above copyright notice,
360    this list of conditions and the following disclaimer in the documentation
361    and/or other materials provided with the distribution.
362
363 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
364 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
365 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
366 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
367 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
368 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
369 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
370 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
371 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
372 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
373 POSSIBILITY OF SUCH DAMAGE.
374
375 = Feedback
376
377 Please let me know if you're using the Wikitext extension in your project.
378 If you have any bug reports or feature requests please open a ticket in
379 the issue tracker at https://wincent.com/issues.
380
381 = Donations
382
383 If you find this extension useful, please consider making a donation via
384 PayPal to win@wincent.com.