Summary

A plug-in for displaying LaTeX in Confluence.  It requires a TeX distribution to be installed separately on the server to function.

Prerequisites

1. You must have a working version of TeX installed on your Confluence server

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.

Installation

Linux/Ubuntu Notes

sudo apt-get install dvipng
sudo apt-get install texlive

There are many many more TeX packages you could install and reference.

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 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 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 mark-up.

Windows Notes

Some Windows 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: mimetex-plugin.zip. Thanks, James!

Note that to use the above 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 latest version of the add-on using the Confluence Plug-in Manager or manually download from the Atlassian Marketplace and install

2. Create a directory called CONFLUENCE_HOME_DIR/shared-home/latex and copy the following files into it:

   • latex.properties

   • latexheader.tex

   • latexfooter.tex

3. Go to Confluence Administration>Add-ons>Manage add-ons and click the Configure button for the LaTeX Plugin

4. You will see the add-on configuration screen. Enter the full path to the latex and dvipng commands.  For example, if you are using a Linux environment it may look something like the below.  Save the configuration when done.
   
   

   

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 header and footer files specify LaTeX commands that are prepended and appended, respectively, to your wiki markup commands.

Also, the 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.

Usage

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

Older Confluence versions	Newer Confluence versions
{latex} \( E=mc^{2} \) {latex}

When the page is previewed or published, the macro should now render the following in your Confluence page:

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

Here is a more complicated example.

Common problems

Error formatting macro

If you just install this add-on 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}

)

Making Markup larger?

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

Unable to find DVI conversion log file

This is often the result of the paths for the latex and dvipng commands not being correctly configured in the add-on's configuration screen. First however, check that these commands are working correctly outside of Confluence (see the above Linux installation notes for an example of how to do this). Once you have confirmed that they are working correctly:

• Go to Confluence administration>Manage add-ons and expand the LaTeX Plugin section

• Click Configure

• Verify that the correct paths to the commands have been entered

• Click Save (this is important to do even if the paths have not been modified to ensure the configuration is saved)

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

Please see the complete version history for a complete picture of compatibility with Confluence: https://marketplace.atlassian.com/plugins/com.tensixtwo.conf.latexmath/versions.

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.

EULA

This software is licensed under the provisions of the Standard EULA from the Atlassian Marketplace Terms of Use as a Marketplace Product.

The "Standard EULA" is reproduced here for convenience. In this case, the "Publisher" is The Plugin People Ltd:

(i) The Publisher is the licensor of the Marketplace Product and Atlassian is not a party to the Publisher EULA or this Standard EULA, as applicable.

(ii) If the Marketplace Product does not include a Publisher EULA that specifies Marketplace Product license rights, Publisher grants you a limited, worldwide, non-exclusive, non-transferable and non-sublicensable license to download and use the Marketplace Product only on hardware systems owned, leased or controlled by you.

(iii) Licenses granted by Publisher are granted subject to the condition that you must ensure the maximum number of Authorized Users that are able to access and use the Marketplace Product concurrently is equal to the number of User Licenses for which the necessary fees have been paid to Atlassian and/or its authorized partners (each, an "Atlassian Expert"). You may purchase additional User Licenses at any time on payment of the appropriate fees to Atlassian or an Atlassian Expert. "User License" means a license granted under this EULA to you to permit an Authorized User to use the Marketplace Product. The number of User Licenses granted to you is dependent on the fees paid by you. "Authorized User" means a person who accesses and uses a Marketplace Product under the EULA and for which the necessary fees have been paid to Atlassian and/or an Atlassian Expert.

(iv) Any information that Publisher collects from you or your device will be subject to any Publisher EULA, privacy notice, or similar terms that the Publisher provides to you, and will not be subject to the Atlassian Privacy Policy (unless Atlassian is the Publisher).

(v) You may not modify, reverse engineer, decompile or disassemble the Marketplace Product in whole or in part, or create any derivative works from or sublicense any rights in the Marketplace Product, unless otherwise expressly authorized in writing by Publisher.

(vi) The Marketplace Product is protected by copyright and other intellectual property laws and treaties. Unless otherwise expressly stated in the Publisher EULA, Publisher or its licensors own all title, copyright and other intellectual property rights in the Marketplace Product, and the Marketplace Product is licensed to you directly by the Publisher, not sold.

Additional Terms

This product is covered by the General Software Product EULA.