Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 110 Next »

This plug-in can be installed and updated via Confluence's built-in Find new add-ons section under Confluence Administration, or via the LaTeX Plugin listing on the Atlassian Marketplace website.


In order to make this add-on available for current versions of Confluence, ownership has been taken on by The Plugin People.  The reference to Stepstone remains to give kudos to the original authors.

Description

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-latex-base
sudo apt-get install texlive-extra-utils
sudo apt-get install texlive-math-extra
sudo apt-get install mimetex

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/latex and copy the following files into it:
  3. Ensure that the full path to the latex and dvipng commands are configured by going to Confluence Administration>Add-ons>Manage add-ons and clicking Configure for the LaTeX Plugin
    • For example, if you are using a Linux environment it may look something like this:

Usage

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

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:

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


which would cause the following to appear 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.

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.

Please do not specify an output file for the dvipng paramaters in latex.properties, as this disables the LaTeX macro!

Common problems

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}

)

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.

  • No labels