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