LaTeX Plugin

In order to make this plugin available for Confluence 3.x, ownership of the plugin has been taken on by ([~javahollic]) and my 1.3 branch has been published as v1.3. I don't work for Stepstone, that reference remains to give kudos to the original authors.

Description/Features

A plug-in for displaying LaTeX in Confluence. (Requires TeX to be installed separately.)

Prerequisites

1. You must have a working version of TeX installed on your Confluence server, and
2. The commands latex and dvipng must be reachable by the $PATH system environment variable.

Both latex and divpng are included in many TeX distributions.

sudo apt-get install dvipng
sudo apt-get install texlive-latex-base
sudo apt-get install texlive-extra-utils
sudo apt-get install texlive-math-extra
sudo apt-get install mimetex

It's a great idea to test your environment before installing the LaTeX plug-in. Make sure you generate a PNG file from a valid latex file at the command line. For instance, download [LaTeX Plugin^simple.tex] and type the following:

latex simple.tex
dvipng simple.dvi

This should generate a file named simple.png containing a familiar equation:

If not, you'll need to troubleshoot your TeX installation before continuing. Try http://www.tug.org/tetex/ and http://sourceforge.net/projects/dvipng/ for more information. (Mac OS X users might prefer the handy MacTeX installation, but be warned that you'll need to add the appropriate /usr/local/teTeX/bin/ subdirectory to your $PATH. And the TeX Users Group recommends the proTeXt package for installing LaTeX on Windows.)

Finally, if you peeked at the [LaTeX Plugin^simple.tex] file contents, don't be discouraged by its complexity. The LaTeX plug-in simplifies the code you'll need to add to your wiki markup.

Windows Users Take Note

Some users have had difficulty getting dvipng to work. In response to this problem, James Matheson has graciously contributed a [mimetex-based version of the plug-in|LaTeX Plugin^mimetex-plugin.zip]. Thanks, James! Note that to use the mimetex version, you will need to ensure that you have a copy of mimetex.exe in the system path. You can find a copy of mimetex.exe in the Mimetex download package at http://www.forkosh.com/mimetex.exe/windows/mimetex.zip

Installation

Once you've tested your TeX installation as above, follow these steps to install the LaTeX plug-in. (Note that CONFLUENCE_HOME_DIR should be replaced with the directory specified in your confluence-init.properties file).

1. Install the latex-plugin-1.2.1.jar using the Confluence Plug-in Manager or the [Confluence Repository Client].
2. Create a directory called CONFLUENCE_HOME_DIR/latex and copy the following files into it:
   • [LaTeX Plugin^latex.properties]
   • [LaTeX Plugin^latexheader.tex]
   • [LaTeX Plugin^latexfooter.tex]

Usage

In your wiki markup, use the parameter-free {latex} macro to wrap your LaTeX code. For example, to generate the same equation you saw in the [LaTeX Plugin^simple.tex] test above, your wiki markup would look like:

{latex}
\( E=mc^{2} \)
{latex}

which would cause the following to appear in your Confluence page:

You'll notice that the wiki markup is much simpler than the test example. See the Configuration section below to learn why.

Here is a more complicated example.

Configuration

The properties files you installed in your CONFLUENCE_HOME_DIR/latex directory allow the simplification of LaTeX commands in your wiki markup. This is because the [LaTeX Plugin^latexheader.tex] and [LaTeX Plugin^latexfooter.tex] files specify LaTeX commands that are prepended and appended, respectively, to your wiki markup commands.

Also, the [LaTeX Plugin^latex.properties] file includes parameters to send to dvipng to further tailor the image generated.

You won't need to edit these files to use the LaTeX plug-in, although the LaTeX Jedi (you'll know if you are one) won't be able to resist tweaking these files.

Common problems

If you just install this plugin without getting Latex installed on your platform (and visible to the confluence install via path - a nod to contegix hosted systems), then you may see the following. A secondary cause is not putting the 'latex' folder in the confluence nominated 'confluence.home' location.

To remedy, find, install and make available to the Confluence PATH (and verify the latex folder is in the right place and readable), the location of the latex binary:

Error formatting macro: latex: java.lang.NullPointerException

( E=mc^
Unknown macro: {2}

)

Logging

To turn logging on, add the following text to CONFLUENCE_INSTALL_DIR/confluence/WEB-INF/classes/log4j.properties (replace CONFLUENCE_INSTALL_DIR with your actual installation directory):

####
# LaTeX debug messages
####
log4j.logger.com.stepstonetech.confluence.plugins.latex=DEBUG,confluencelog
log4j.additivity.com.stepstonetech.confluence.plugins.latex=false

This will print all LaTeX debugging messages to your atlassian-confluence.log file.

To turn logging off, change the word DEBUG to ERROR.

Compatibility

We've successfully used the LaTeX plug-in in Linux and Mac OS X environments with:

• latex version 3.0, 'texlive-latex-base, 2009-10 (maverick)'
• dvipng versions 1.6, 1.8, 1.13
• java 1.6.0
• Confluence 2.x - 3.4

Tips & Tricks

If you would like to reuse Latex statements several times on a page, or across multiple pages, you may like to start a Latex statement library. Create a page specifically for storing statements and add a child page for each statement. Then use the [Include Page macro] to embed those statement pages wherever they are needed.