Ikiwiki plugin for the Pandoc markdown processor
================================================

Pandoc <http://johnmacfarlane.net/pandoc/> has a richer syntax and more
flexible configuration than Markdown, and is also able to parse a variety of
other syntaxes. This plugin can be configured to generate wiki pages from LaTeX
and reST sources, as well as markdown. It can also be configured to convert
inline TeX using a variety of methods. And, if Pandoc was compiled with the
-fhighlighting, it can be configured to apply syntax highlighting to code
blocks and `inline code spans`.




## Options ##

### Available in Ikiwiki's web preferences ###

#. File extension for Markdown files (defaults to mdwn)

#. Use smart quotes, dashes, and ellipses

#. Generate ASCII instead of UTF8.

#. Number section headings in generated pages

#. Wrap sections in `<div>` tags (or `<section>` tags in HTML5), and
   attach identifiers to the `<div>` rather than th header itself. This
   allows the section to be styled or manipulated via javascript.

#. Obfuscate emails using HTML character references

#. Generate HTML5 (the Ikiwiki html5 setting should also be set)

#. Classes to use for all indented code blocks (these can also be 
   specified differently from block to block; see below)


### Have to be configured manually in your wiki's *.setup file ###

#. Path to pandoc executable (defaults to /usr/local/bin/pandoc)

#. Enable Pandoc processing of LaTeX documents

#. Enable Pandoc processing of reStructuredText documents

#. Method for handling inline TeX (see below)


## Details ##

### Syntax Coloring ###

Pandoc can be configured to apply classes globally to all its inline code blocks (for example, `numberLines` or `perl`). Alternatively, code blocks can be written in this style:

	~~~
	if (a > 3) {
	   moveShip(5 + gravity, DOWN);
	}
	~~~

The line of `~~~` can be longer than 3 characters, if you like. This manner of writing indented code blocks also permits us to specify the block's specific syntax, which might be different from other blocks:


	~~~{.haskell .numberLines}
	if (a > 3) {
	   moveShip(5 + gravity, DOWN);
	}
	~~~

If Pandoc wasn't compiled with syntax highlighting support, such a code block will be processed like this:

	<pre class="haskell">
		<code>
		...
		</code>
	</pre>


You can also specify the syntax for inline code spans: `` `some code`{.haskell} ``.

This functionality overlaps somewhat with Ikiwiki's `highlight` plugin and `format` directive:

	[[!format  perl """
	print "hello, world\n";
	"""]]

You'll have to decide which facility better suits your needs.

### Tables ###

Pandoc has a native [table-handling syntax](http://johnmacfarlane.net/pandoc/README.html#tables). This overlaps somewhat with Ikiwiki's `table` directive. Here too, you'll have to decide which facility better suits your needs.


### Inline TeX processing ###

Pandoc recognizes inline TeX and can be configured to display it on the web using a variety of tools.

#. You can use MathJax <http://www.mathjax.org/>. This requires copying the `mathjax.tmpl` file that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`. (Available since Pandoc 1.8.)

#. jsMath is the predecessor to MathJax. It doesn't give as nice results, and is harder to install, but it's also an option. Download jsMath and jsMath-fonts <http://www.math.union.edu/~dpvc/jsMath/> and install them so that they're served from the root of your server, that is, from `/jsMath/...` Also, copy the file `jsmath.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`.

#. A different JavaScript solution is LatexMathML <http://math.etsu.edu/LaTeXMathML/>. Again, this gives less good results than MathJax, but it's easier to install than jsMath. Download the `LaTeXMathML.js` and `LaTeXMathML.standardarticle.css` files and install them so that they're served from the root of your server.  Also, copy the file `latexmathml.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`.

#. Instead of using JavaScript, a different approach is to build and install a cgi on your server. MathTeX <http://www.forkosh.com/mathtex.html> gives good results, but needs LaTeX to be available on the server. This plugin assumes that if you're using MathTeX, it will be served from `/cgi-bin/mathtex.cgi`.

#. MimeTeX <http://www.forkosh.com/mimetex.html> is the predecessor to MathTeX. It doesn't give as nice results, but will work on less equipped servers. This plugin assumes that if you're using MimeTeX, it will be served from `/cgi-bin/mimetex.cgi`.

#. Or you could use a third-party cgi, such as Google Charts API <http://code.google.com/apis/chart/>. (Available since Pandoc 1.6.)

#. Another option is to directly render the TeX into MathML. Browser support for displaying MathML is coming slowly. Firefox supports it well, but WebKit/Chrome is only beginning to. To process inline TeX via this method, copy the file `mathml.tmpl` that accompanies this plugin to a template directory seen by your wiki. Rename the file to `page.tmpl`. You should also arrange for the file `mathml.js` to be served from the root of your server; this file helps provide a better fallbacks for browsers that can't display the MathML. This method also requires htmlscrubber to be disabled, at least for pages containing MathML. (Available since Pandoc 1.5.)

#. If none of the other options are enabled, Pandoc will attempt to render inline TeX using Unicode characters, in so far as that's possible.


If none of these options work for you, you could check out the [teximg plugin](http://ikiwiki.info/plugins/teximg/); this works something like MathTex, above. You could also look into using
`itex2MML`; Jason Blevins <http://jblevins.org/projects/ikiwiki/> has a plugin
for using that tool together with Markdown. (A newer version is mentioned at <http://ikiwiki.info/todo/mdwn_itex/>.)

See also <http://ikiwiki.info/todo/latex>, which describes a number of other works-in-progress for rendering LaTeX in Ikiwiki.)


### TeX macros ###

Another nice Pandoc feature is that it parses and uses `\newcommand` and `\renewcommand` macro definitions:

	\newcommand{\tuple}[1]{\langle #1 \rangle}
	...
	$\tuple{a, b, c}$


## Release Notes ##

 * v1.0 (1 June 2011) Initial release. Based on Jason Blevin's original <http://jblevins.org/projects/ikiwiki/>.


<!-- vim: ft=pdc
-->