[edit] [comment] [remove] |2006-02-17| e1 # Wiky: A Bidirectional Markup Converter

Wiky is a clientside Wiki markup to HTML converter written in javascript. As it is bidirectional, it can convert Wiki markup to HTML and later convert that generated HTML text back to Wiki markup. Optionally Wiky will create math formulas from a simple notation similar to LaTeX.

Wiky example text and output

Wiky is neither an editor nor a widget, though it might be used by these. It is just a converter.

The primary object of Wiky's developement was its use in a lightweight eLearning environment. It had to meet the requirements:

  • Clientside only.
  • Creating validating XHTML markup, which is …
  • … cross browser with no need of plugins or addons.
  • Minimal CSS dependency.
  • Suitable for inplace editing with Ajax components and weblogs.
  • Easily extensible and modifyable Syntax.

You can play with it in the WikyBox and download the most current version. I have tested Wiky for several month now with a couple of students using

  • Firefox 1.5
  • Internet Explorer 6
  • Opera 8.5

You may use it freely under the Creative Commons GNU LGPL License.

 

[edit] [comment] [remove] |2006-02-17| e2 # Wiky Syntax

Wikitext is written in a lightweight markup language with specific syntax rules. The choice of a wiki syntax is nontrivial, as there is no common wiki markup standard. Even if there are some attempts of standardization, no final agreement can be seen.

You can comfortably compare syntax differences with WikiMatrix.

Wiky's syntax is heavily influenced by markdown and MediaWiki.

Wiky Markup HTML
Block Formatting
= H1 =
...
====== H6 ====== 		<h1> H1 </h1<
...
<h6> H6 </h6>
paragraphs separated

by an empty line 		<p>paragraphs separated</p>
<p>by an empty line</p>
line break by two\\
slashes followed by a space or newline 		line break by two<br/>
slashes followed by a space or newline
["quotation"] <blockquote><p>quote</p></blockquote>
[%code block%] <pre>code block</pre>
Inline Formatting
*strong* <strong>strong</strong>
_emphasized_ <em>emphasized</em>
^superscript^ <sup>superscript</sup>
~subscript~ <sub>subscript</sub>
%code% <code>code</code>
?ABBR(abbreviation)? <abbr title="abbreviation">ABBR</abbr>
Links & Images
http://u.ri <a href="http://u.ri">http://u.ri</a>
[http://u.ri, title] <a href="http://u.ri">title</a>
uri/image.png <img src="uri/image.png" alt="uri/image.png"/>
[img:uri/image.png,title] <a href="http://u.ri">title</a>
[http://u.ri, title] <img src="uri/image.png" alt="title" title="title"/>
Lists
; term: definition <dl><dt>term</dt><dd>definition</dd></dl>
* unordered
* list 		<ul>
<li class="u">unordered</li>
<li class="u">list</li></ul>
1. ordered
1. list 		<ol style="list-style-type:decimal;">
<li class="1">ordered</li>
<li class="1">list</li></ol>
Table
[|one|two|
||three|four|] 		<table><tr><td>one</td><td>two</td></tr>
<tr><td>three</td><td>four</td></tr></table>
 

[edit] [comment] [remove] |2006-02-17| e3 # Usage and Implementation

Wiky consists of some ordered sets of rules based on regular expressions. It doesn't rely on external CSS, so its HTML output can be used smoothly with RSS or ATOM feeds. The use of internal style attributes is possible and useful, but always an option.

Wiky is lightweight (~20 kB) and implemented as a single static object with two public methods 

Wiky.toHtml(wikistr);
Wiky.toWiki(htmlstr);

for converting some text from Wiki markup to HTML and vice versa. A minimal Wiky demo application looks like so. 

<html>
  <head>
    <script type="text/javascript" src="wiky.js"></script>
  </head>
  <body>
    <textarea id="input"></textarea>
    <button onclick="alert(Wiky.toHtml(document.getElementById('input').value));">
       toHtml
    </button>
  </body>
</html>
 

[edit] [comment] [remove] |2006-02-17| e4 # Extensibility and Modifications

The simple architecture of Wiky makes adding extensions easy. There are several rule sections, implemented as arrays. 

var Wiky = {
  rules: { // wiki to html
    pre: [],
    post: [],
    nonwikiblocks: [],
    wikiblocks: [],
    nonwikiinlines: [],
    wikiinlines: [],
    escapes: [],
    shortcuts: [],
    code: [],
    lang: [],
  },
  inverse: { // html to wiki
  /* ... */
  }
};

Each rule consists of a regular expression and a corresponding string or function template in case of a match. 

{ rex:/.../g, tmplt:"..." },

So adding one ore more rules, you simply add those to the corresponding rule sections. If we would want to map the shortcut '(R)' to the character '®', we could write (preferrable in a separate file) 

Wiky.rules.shortcuts = Wiky.rules.shortcuts.concat(
  { rex:/\(R\)/g, tmplt:"&#174;" });
Wiky.inverse.shortcuts = Wiky.inverse.shortcuts.concat(
  { rex:/&#174;/g, tmplt:"(R)" });

When adding rules, you have to take care, if they interfere with existing rules. Wiky comes with two extensions:

  • wiky.lang.js = syntax highlighting for XML and Javascript.
  • wiky.math.js = LateX like math formulas.

The mechanism to extend or modify these rules is transparent and easy as in the example above.

 

[edit] [comment] [remove] |2006-02-17| e5 # Math Formulas

The primary use case of creating and editing learning content also includes the requirement of handling math formulas. A LaTeX style markup to describe math formulas is simple, intuitive and well proven for years.

So Wiky uses a markup similar to LaTeX as input format. It creates HTML+CSS for math rendering in order to be cross browser without the need of plugins (So note: 'wiky.math.js' does rely on CSS — in contrast to 'wiky.js').

The technique used here is heavily inspired by George Chavchanidze's great project site at Maiden. Wiky implements only a subset of Maiden's functionality and directly converts to HTML instead of XML.

In case you prefer to directly generate MathML, I would like to recommend Peter Jipsen's cool LaTeX to MathML translator AsciiMathML.

I might write more about Wiky's math capabilities in a future article. You can try it out in WikyBox and will also find a short syntax reference there.

If you want to use the math extension of Wiky, you need to include the files:

  • 'wiky.js'
  • 'wiky.math.js'
  • 'wiky.math.css'