From: W. Trevor King Date: Mon, 4 Oct 2010 18:13:41 +0000 (-0400) Subject: Document mdwn_itex plugin. X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=aac19539df17ea0d76ccadbe862fedb4cc57591d;p=ikiwiki.git Document mdwn_itex plugin. --- diff --git a/doc/ikiwiki/itex.mdwn b/doc/ikiwiki/itex.mdwn new file mode 100644 index 000000000..7d128a490 --- /dev/null +++ b/doc/ikiwiki/itex.mdwn @@ -0,0 +1,10 @@ +[[!meta robots="noindex, follow"]] + +[itex][] is a math markup language that resembles LaTeX. You can +translate itex to MathML with tools such as [itex2MML][]. The +[[plugins/mdwn_itex]] plugin can be used to automatically convert +embedded itex to MathML for pages that otherwise use the [[markdown]] +markup language. + +[itex]: http://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html +[itex2MML]: http://golem.ph.utexas.edu/~distler/blog/itex2MML.html diff --git a/doc/plugins/mdwn_itex.mdwn b/doc/plugins/mdwn_itex.mdwn new file mode 100644 index 000000000..e9636b9c2 --- /dev/null +++ b/doc/plugins/mdwn_itex.mdwn @@ -0,0 +1,67 @@ +[[!template id=plugin name=mdwn core=0 author="[[W. Trevor King]]"]] +[[!tag type/format]] + +This plugin lets ikwiki convert files with names ending in +`.mdwn_itex` to html. It uses the [[ikiwiki/markdown]] minimal markup +language with embedded [[ikiwiki/itex]]. The itex portion of the +processing is handled by [itex2MML][], which converts the itex to +[MathML][]. The markdown portion of the processing is handled by the +[[mdwn]] plugin, so alternative markdown implementations are supported +by configuring that plugin. + +In order to generate valid pages with MathML, you'll need to patch your +templates to use an appropriate `DOCTYPE`: + + diff -ru /usr/share/ikiwiki/templates/page.tmpl .ikiwiki/templates/page.tmpl + --- /usr/share/ikiwiki/templates/page.tmpl 2010-09-30 08:58:51.000000000 -0400 + +++ .ikiwiki/templates/page.tmpl 2010-09-30 09:10:02.000000000 -0400 + @@ -1,8 +1,12 @@ + + + - + - + + + + + + + + + + +To setup the plugin, add config options along the lines of: + + # plugins to add to the default configuration + add_plugins => [qw{ ... mdwn_itex ...}], + # plugins to disable + disable_plugins => [qw{... htmlscrubber htmltidy ...}], + + # location of template files + templatedir => '/path/to/patched/templates', + + # mdwn_itex plugin + # path to the itex2MML binary + itex2mml => '/usr/local/bin/itex2MML', + # autonumber display equations? + itex_num_equations => 1, + +Create new files with the `.mdwn_itex` extension, and start +including itex: + + Euler's identity + + \[ e^{i \pi} + 1 = 0 \] + + has lots of fun constants: $e$, $i$, $\pi$, $1$, and $0$. + +The [[htmlscrubber]] and [[htmltidy]] plugins must be disabled because +otherwise they [strip][scrubber_strip] [out][tidy_strip] the MathML +markup. + +[itex2MML]: http://golem.ph.utexas.edu/~distler/blog/itex2MML.html +[MathML]: http://www.w3.org/Math/ +[scrubber_strip]: http://ikiwiki.info/todo/svg/ +[tidy_strip]: http://lists.w3.org/Archives/Public/html-tidy/2006JanMar/0052.html