+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 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/>, which also 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
+-->
projects / ikiwiki-pandoc.git / commitdiff