{repository-plugin:key=com.stepstonetech.confluence.plugins.latex}
|| SVN | [project|https://svn.atlassian.com/svn/public/contrib/confluence/latex-plugin], [branches|https://svn.atlassian.com/svn/public/contrib/confluence/latex-plugin/branches], [tags|https://svn.atlassian.com/svn/public/contrib/confluence/latex-plugin/tags], [trunk|https://svn.atlassian.com/svn/public/contrib/confluence/latex-plugin/trunk], [all jars|https://svn.atlassian.com/svn/public/contrib/confluence/latex-plugin/dist] ||

(i) 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.

{tip}This plug-in can be installed and updated via the [Confluence Repository Client|CONFEXT:Confluence Repository Client]. However, see the instructions below for adding the necessary configuration files and installing TeX before using the LaTeX plug-in.
{tip}

h2. Description/Features
{excerpt}A plug-in for displaying LaTeX in Confluence.{excerpt} (Requires TeX to be installed separately.)

h2. Prerequisites

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

Both {{latex}} and {{divpng}} are included in many TeX distributions.

{tip:title=Ubuntu 10.10 install steps}
{noformat}
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
{noformat}
There are many many more tex packages you could install and reference...
{tip}


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:
{noformat}
latex simple.tex
dvipng simple.dvi
{noformat}
This should generate a file named {{simple.png}} containing a familiar equation: !simple.png!

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|http://www.tug.org/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|http://tutex.tug.org] recommends the [proTeXt|http://tutex.tug.org/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.

h2. 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]



h2. 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).
# Install the [latex-plugin-1.2.1.jar|http://svn.atlassian.com/svn/public/contrib/confluence/latex-plugin/dist/latex-plugin-1.2.1.jar] using the Confluence Plug-in Manager or the [Confluence Repository Client|CONFEXT:Confluence Repository Client].
# 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]

h2. Usage

{note}Do not use the 'Rich Text' editor to write LaTeX markup. The rich text editor escapes some of the LaTeX characters, generating unpredictable output.{note}

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:
{noformat}
{latex}
\( E=mc^{2} \)
{latex}
{noformat}
which would cause the following to appear in your Confluence page: !simple.png!

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|Complex LaTeX Example].

h2. 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.
{note}Please do not specify an output file for the {{dvipng}} paramaters in {{latex.properties}}, as this disables the LaTeX macro\!
{note}

h2. 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:
{noformat}
Error formatting macro: latex: java.lang.NullPointerException

( E=mc^
Unknown macro: {2}

)
{noformat}


h2. 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):
{noformat}
####
# LaTeX debug messages
####
log4j.logger.com.stepstonetech.confluence.plugins.latex=DEBUG,confluencelog
log4j.additivity.com.stepstonetech.confluence.plugins.latex=false
{noformat}
This will print all LaTeX debugging messages to your {{atlassian-confluence.log}} file.

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

h2. 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

h2. 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|DOC:Include Page Macro] to embed those statement pages wherever they are needed.