Added module, wrote readme

Author: bk

IkiWiki/Plugin/mathjax.pm

@@ -0,0 +1,96 @@
+package IkiWiki::Plugin::mathjax;
+
+use warnings;
+use strict;
+use IkiWiki 3.00;
+use MIME::Base64;
+
+# Strategy:
+## - filter replaces normal TeX delimiters with imath and dmath directives
+##   (perhaps while considering a mathconf directive); also, it adds a script
+##   block if there is any math on the page relevant.
+## - preprocess handles the directives themselves.
+##
+## Later: config hooks for mathjax script tag and mathjax config block
+##
+
+sub import {
+    hook(type => "filter", id => "mathjax", call => \&filter);
+    hook(type => "format", id=>"mathjax", call=> \&format);
+}
+
+sub format {
+    my %params = @_;
+    my $content = $params{content};
+    return $content unless $content =~ /\!\!mathjaxbegin/; #]/{{
+    $content =~ s{\!\!mathjaxbegin-i!! (.*?)\s\!\!mathjaxend-i\!\!}{'\('.decode_base64($1).'\)'}ges; #{
+    $content =~ s{\!\!mathjaxbegin-d!! (.*?)\s\!\!mathjaxend-d\!\!}{'\['.decode_base64($1).'\]'}ges; #{
+    my $scripttag = _scripttag();
+    $content =~ s{(</head>)}{$scripttag\n$1}i; #}{
+    return $content;
+}
+
+sub filter (@) {
+    my %params=@_;
+    my $content = $params{content};
+    return $content unless $content =~ /\$[^\$]+\$|\\[\(\[][\s\S]+\\[\)\]]/;
+    # first, handle display math...
+    $content =~ s{(?<!\\)\\\[(.+?)(?<!\\)\\\]}{_escape_mathjax('d', $1)}ges; #};[}
+    $content =~ s{(?<!\\)\$\$(.+?)(?<!\\)\$\$}{_escape_mathjax('d', $1)}ges; #};[}
+    # then, the inline math -- note that it must stay on one line
+    $content =~ s{(?<!\\)\\\((.+?)(?<!\\)\\\)}{_escape_mathjax('i', $1)}ge; #};[}
+    # note that the 'parsing' of $..$ is extremely fragile
+    $content =~ s{(?<!\\)\$(.+?)(?<!\\)\$}{_escape_mathjax('i', $1)}ge; #};[}
+    return $content;
+}
+
+sub _escape_mathjax {
+    my ($mode, $formula) = @_;
+    my %modes = qw/i inline d display/;
+    my $directive = "!!mathjaxbegin-$mode!! ";
+    $formula =~ s/"/&quot;/g;
+    $formula =~ s/&/&amp;/g; #"/}[{
+    $formula =~ s/</&lt;/g;
+    $formula =~ s/>/&gt;/g; #{"
+    $directive .= encode_base64($formula);
+    $directive .= " !!mathjaxend-$mode!!";
+    return $directive;
+}
+
+sub _scripttag {
+    my $config = 'TeX-AMS_HTML'; # another possibility: TeX-AMS-MML_HTMLorMML
+    return '<script type="text/x-mathjax-config">'
+      . 'MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "AMS"} } });'
+      . '</script>'
+      . '<script type="text/javascript" '
+      . 'src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config='
+      . $config
+      . '"></script>';
+}
+
+sub _scriptblock {
+    return qq%
+<script type="text/javascript">//<![CDATA[
+(function () {
+  if (window.MathJax && MathJax.Hub) return;
+  var script = document.createElement("script");
+  script.type = "text/javascript";
+  script.src  = "http://cdn.mathjax.org/mathjax/latest/MathJax.js";
+
+  var config = 'MathJax.Hub.Config({' +
+                 'extensions: ["tex2jax.js"],' +
+                 'jax: ["input/TeX","output/HTML-CSS"],' +
+                 'TeX: { equationNumbers: { autoNumber: "AMS" } }' +
+               '});' +
+               'MathJax.Hub.Startup.onload();';
+
+  if (window.opera) {script.innerHTML = config}
+               else {script.text = config}
+
+  document.getElementsByTagName("head")[0].appendChild(script);
+})();
+//]]></script>
+%;
+}
+
+1;

README.md

@@ -1,4 +1,39 @@
-ikiwiki-plugin-mathjax
-======================
+IkiWiki::Plugin::mathjax
+========================
+
+IkiWiki's default support for math is rather clumsy and old-fashioned. Also, it
+requires a working LaTeX installation.
+
+A much better option is Pandoc, available to IkiWiki users through the
+IkiWiki::Plugin::pandoc plugin (which can be found in a few versions on
+GitHub). However, it has some drawbacks as well:
+
+- If you are using shared hosting, Pandoc can be cumbersome to
+  install. 
+- If you don't need its markdown extensions, footnotes,
+  extra source and target formats, bibliography support, etc., but just want to
+  have some nicely formatted math on your wiki/blog, Pandoc seems like
+  overkill.
+- Because an external process will be called for each page, a rebuild of a
+  large wiki takes an uncomfortably long time.
+- It is difficult to get Pandoc with MathJax and the smiley plugin to work
+  together, since the latter tends mangle the content which MathJax is supposed
+  to work its magic on.
+- You need to change page.tmpl, which means that you have to check for
+  compatibility with the new page.tmpl every time you upgrade IkiWiki.
+
+This simple plugin solves these issues, making it easy to use MathJax in
+IkiWiki. Features:
+
+- No changes to page.tmpl are needed -- the MathJax Javascript is only loaded
+  on pages where it is needed.
+- Both display ($$...$$ or \\[...\\]) and inline ($...$ or \\(...\\)) math are
+  supported. Just take care that **inline math must stay on one line** in your
+  markdown source.  A single literal dollar sign in a line does not need to be
+  escaped, but two do.
+
+If you want to change the MathJax configuration, you currently must edit the
+source of the module. I may later add configuration hooks so that one may
+control its behaviour through the setup file for the wiki. Let me know if you
+need this.
 
-MathJax plugin for IkiWiki