Skip to end of metadata
Go to start of metadata

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.

30 Comments

  1. Unknown User (leonk)

    Hello,

    I have a problem using Latex plugin.

    I've installed all needed tools with:

    # yum install tetex tetex-fonts tetex-dvips tetex-latex ghostscript

    and installed plugin as described on this page.

    Now when I try to use your sample to create a formula in a wiki markup:

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

    I'm getting "Unable to find DVI conversion log file." message in Confluence.
    I've enabled logging and I'm getting this in atlassian-confluence.log:

    2010-06-17 14:28:53,371 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Started the LaTeX markup to PNG file conversion.
    2010-06-17 14:28:53,375 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Creating a new tex file with some wiki markup.
    2010-06-17 14:28:53,377 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Writing the LaTeX header:
    \documentclass{article}
    \usepackage{amsmath}
    \usepackage{amsthm}
    \usepackage{amssymb}
    \usepackage{bm}
    \newcommand{\mx}[1]{\mathbf{\bm{#1}}} % Matrix command
    \newcommand{\vc}[1]{\mathbf{\bm{#1}}} % Vector command
    \newcommand{\T}{\text{T}}                % Transpose
    \pagestyle{empty}
    \begin{document}
    
    2010-06-17 14:28:53,378 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Creating a new TEX file with a unique filename.
    2010-06-17 14:28:53,380 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg The new TEX file has been created: LaTeX49624.tex
    2010-06-17 14:28:53,381 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg The common working directory has been set to: /srv/confluence.data/temp
    2010-06-17 14:28:53,382 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg The common filename to be used for all generated files has been set to: LaTeX49624
    2010-06-17 14:28:53,384 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Starting writing LaTeX markup to: LaTeX49624.tex
    2010-06-17 14:28:53,385 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Finished writing LaTeX markup to: LaTeX49624.tex
    2010-06-17 14:28:53,386 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg The tex file should be created and called: LaTeX49624tex
    2010-06-17 14:28:53,387 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Creating a a new dvi file from the tex file using the command: latex
    2010-06-17 14:28:53,389 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Running the process: latex
    2010-06-17 14:28:53,390 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Using the arguments:
    2010-06-17 14:28:53,391 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg ... arg 1 = -interaction=batchmode
    2010-06-17 14:28:53,392 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg In working directory: /srv/confluence.data/temp
    2010-06-17 14:28:53,615 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Process failed with exit code: 1
    2010-06-17 14:28:53,618 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg Unable to find DVI conversion log file.
    2010-06-17 14:28:53,620 DEBUG [TP-Processor8] [confluence.plugins.latex.LatexMacro] debugMsg /srv/confluence.data/temp/LaTeX49624.log (No such file or directory)
    

    Running this manually, works as it should 

    $ latex simple.tex
    This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4)
    entering extended mode
    (./simple.tex
    LaTeX2e <2003/12/01>
    Babel <v3.8d> and hyphenation patterns for american, french, german, ngerman, b
    ahasa, basque, bulgarian, catalan, croatian, czech, danish, dutch, esperanto, e
    stonian, finnish, greek, icelandic, irish, italian, latin, magyar, norsk, polis
    h, portuges, romanian, russian, serbian, slovak, slovene, spanish, swedish, tur
    kish, ukrainian, nohyphenation, loaded.
    (/usr/share/texmf/tex/latex/base/article.cls
    Document Class: article 2004/02/16 v1.4f Standard LaTeX document class
    (/usr/share/texmf/tex/latex/base/size12.clo))
    (/usr/share/texmf/tex/latex/ntgclass/a4.sty)
    No file simple.aux.
    [1] (./simple.aux) )
    Output written on simple.dvi (1 page, 320 bytes).
    Transcript written on simple.log.
    
    [lkolchin@vera070 ~]$ dvipng simple.dvi
    This is dvipng 1.5 Copyright 2002-2005 Jan-�ke Larsson
    [1]
    
    [lkolchin@vera070 ~]$ ls -l
    total 24
    -rw-r--r-- 1 lkolchin its 1759 Jun 17 15:13 simple1.png
    -rw-r--r-- 1 lkolchin its    8 Jun 17 15:13 simple.aux
    -rw-r--r-- 1 lkolchin its  320 Jun 17 15:13 simple.dvi
    -rw-r--r-- 1 lkolchin its 2608 Jun 17 15:13 simple.log
    -rw-r--r-- 1 lkolchin its   95 Nov 24  2009 simple.tex
    

    Any help? Clues?

    1. Unknown User (jvang)

      I have the same problem too. I wonder what exit code 1 means? I thought this was a permission issue, but the fact that the .tex file is being created in the conversion directory (for you and me), there is no reason why the .log and .dvi files couldn't be created there too (they would all be using the same user/account via tomcat). I am looking at the code, and there's really no magic involved.

      1. Unknown User (leonk)

        Hi Jake,

        Did you manage to resolve this issue somehow?

        1. Unknown User (cole57)

          I was seeing the same behavior as Leon was with CentOS 5.5, confluence 3.4, and the tomcat6-6.0.18-9.jpp5 rpm except that when I ran "su - tomcat" and tried latex from the command line it didn't execute properly. I could run latex from an ordinary user account successfully but it would fail as the tomcat user. This is what I was seeing:

          -sh-3.2$ latex -interaction=batchmode /CONFLUENCE_HOME/temp/LaTeX5954045436938176686.tex
          This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4)
          kpathsea: Running mktexfmt latex.fmt
          fmtutil: format directory `/usr/share/tomcat6/.texmf-var/web2c' does not exist.
          I can't find the format file `latex.fmt'!
          

          The tomcat user that is installed from the rpm is different than ordinary user accounts because it doesn't have write permissions on it's home directory. From the fmtutil error message you can tell that latex is trying to create some files in tomcat's home directory (/usr/share/tomcat6) but isn't able to due to the directory permissions. Here's what I did to fix the problem:

          su -
          chmod 777 /usr/share/tomcat6
          su - tomcat
          latex -interaction=batchmode /CONFLUENCE_HOME/temp/LaTeX5954045436938176686.tex
          

          Latex should execute successfully at this point and when you look in /usr/share/tomcat6 you'll see a new directory generated by latex called ".texmf-var". You also will probably see a .bash_history file and the latex-generated files (aux/dvi/log) which can all be removed. Don't forget to repermission the tomcat6 directory after you're done.

          [root@hostname tomcat6]# pwd
          /usr/share/tomcat6
          [root@hostname tomcat6]# ls -la
          total 20
          drwxr-xr-x  4 root   root   4096 Nov  3 10:32 .
          drwxr-xr-x 91 root   root   4096 Nov  1 17:24 ..
          drwxr-xr-x  2 tomcat tomcat 4096 Sep 29 14:36 bin
          lrwxrwxrwx  1 root   root     12 Sep 28 13:34 conf -> /etc/tomcat6
          lrwxrwxrwx  1 root   root     23 Sep 28 13:34 lib -> /usr/share/java/tomcat6
          lrwxrwxrwx  1 root   root     16 Sep 28 13:34 logs -> /var/log/tomcat6
          lrwxrwxrwx  1 root   root     23 Sep 28 13:34 temp -> /var/cache/tomcat6/temp
          drwxrwxrwx  3 tomcat tomcat 4096 Nov  3 10:29 .texmf-var
          lrwxrwxrwx  1 root   root     24 Sep 28 13:34 webapps -> /var/lib/tomcat6/webapps
          lrwxrwxrwx  1 root   root     23 Sep 28 13:34 work -> /var/cache/tomcat6/work
          

          This might not be the best solution but it worked for me. Hope it helps.
          Colin

          1. Unknown User (leonk)

            Hello Colin,

            Our Java programmer actually did some quick hack of this plugin to make path configuration working.

            I've also had to do the following to make it work (which is very similar to what you've done):

            # mkdir -p /usr/share/.texmf-var/
            # cp -a /usr/share/texmf-var/web2c /usr/share/.texmf-var/
            # chown -R tomcat:tomcat /usr/share/.texmf-var

            I can also send you our latex-plugin-1.3.3-SNAPSHOT.jar if you want ;)

            Thanks for sharing info.

            Leon Kolchinsky

            1. Unknown User (cole57)

              Thanks Leon, but that won't be necessary - the plugin is now working for us (smile)

            2. Unknown User (bcopy)

              Hello Leon,

              I would be interested in the latex-plugin-1.3.3-SNAPSHOT.jar - we are also having path configuration woes, and the procedure above did not seem to work for us,

              Cheers,

              Brice

              1. Unknown User (leonk)

                Sure,

                Here you go - http://rapidshare.com/files/454062807/latex-plugin-1.3.3-SNAPSHOT.jar

                Don't forget to make a copy of /usr/share/texmf-var/web2c and chown it:

                [root@vera070 ~]# mkdir -p /usr/share/.texmf-var/
                [root@vera070 ~]# cp -a /usr/share/texmf-var/web2c /usr/share/.texmf-var/
                [root@vera070 ~]# chown -R tomcat:tomcat /usr/share/.texmf-var

                Cheers,

                Leon

  2. Is there any way to cache the content?

    We've got some pages with around 90 Latex formulas on it, and it takes around 3 minutes to render.

    1. Unknown User (leonk)

      Did you try cache plugin?

      1. Hi léon,

        I try and it doesn't work at all, the Latex formulas don't appear between the macro {cache}

        1. Hi Cyrille, Leon,

          I got the same result.

          The Info on the Cache Macro page says:

          Macros known to not work with the cache macro

          .....
          Other macros that generate dynamic images

          Latex generates dynamic images from what I can see.

          1. Unknown User (leonk)

            It was just a suggestion.

            IMHO, Latex plugin needs a cache feature, so it won't regenerate images from formulas you don't change.

  3. Unknown User (anders_sjoegren)

    Hello,

    I am a new user to confluence and this plugin. We have the plugin running and the output is fine until the latex body reaches some number of rows, say 50 rows or so. When this happens, the output is reduced to only some of the last rows. I have not grasped the problem fully, but I am wondering if anyone has had the same issue. I have tried different settings in the latex.properties file. For some settings the image size seems right but most of the content is gone (except the last rows).

    I am thinking the issue is related to the paper size. Setting documentclass to a5paper makes the problem worse. I have not used dvipng before. It seems it generates one image per page. I think I am only seeing the last page. Don't know what to do about it...

    Thanks,

    Anders

    1. Unknown User (ustinjay)

      Hi,

      I am also experiencing this problem, and it's annoying. It's reproducible as you described -- if the rendered text file contains more than ~50 lines, the LaTeX plugin will truncate the output.

      Here's an example. We have 100 lines:

      {latex}
      This is Line 1.
      
      This is Line 2.
      
      ...
      
      This is Line 100.
      {latex}
      

      Then we delete every other line, so we have blank lines separating textual ones:

      {latex}
      This is Line 2.
      
      
      This is Line 4.
      
      
      ...
      
      
      This is Line 100.
      {latex}
      

      The output LaTeX shows only the last 4 lines!

      This is Line 94.
      
      This is Line 96.
      
      This is Line 98.
      
      This is Line 100.
      

      Any thoughts? I love the wiki and this plugin, but this 50-line limitation is kind of cramping my style...

      Justin

      1. Unknown User (ustinjay)

        I think Anders is right -- it's a problem with the paper size. If the rendered text is multiple pages, the plugin only shows the last page.

        I discovered this by writing a chunk of LaTeX which was as long as you could make it without truncating, then printing it. On A4 paper, it just barely fits.

        As another test, I used newpage to force LaTeX to create multiple pages:

        {latex}
        This should be on the first page.
        \newpage
        This should be on the second page.
        {latex}
        

        The rendered output is

        This should be on the second page.
        

        Anders mentioned it gets worse with the documentclass set to A5 paper -- this makes sense, because A5 is a little smaller than A4, so you'll make new pages sooner.

        If your documentclass could somehow specify an infinitely-long page, that would circumvent the problem -- you'd end up with a single long LaTeX rendering. But you couldn't print it onto paper -- it's a single huge png and your browser probably won't break it properly when printing.

        Justin

        1. Hi,

          a workaround for latex content longer than one page is to enlarge the page using the \enlargethispage{} latex command. Just put it at the top of your latex content. Adjust the size to suit.

          cheers, Phil

          {latex}
          \enlargethispage{1000mm}    % keeps everything on one page so it is returned by latex macro.
          
          ...
          
          {latex}
          
  4. Unknown User (macrobat)

    I am having the exact same problem ( i.e. Unable to find DVI conversion log file).

    I guess my Confluence installation doesnt really have the correct PATH setting, but to confirm this I would need some way to see the settings of the environment variables... How could I issue a system call or some command to the OS (like "echo $PATH")?

    Cheers, Robert

  5. Unknown User (relitech)

    I am having the exact same problem ( i.e. Unable to find DVI conversion log file) but on a Windows system.

    I installed the Plugin, mimetex.exe and the 3 files in the /latex folder.

    What else do I need to install or configure?

    Thanks, Egbert

  6. Unknown User (jenleehicks)

    Are there any plans to make this plug in compatible with Confluence 4.0?

    Thanks!

    Jen

    1. In time yes, I just have other projects Im working on,

    2. Unknown User (tensixtwo)

      Hey, check out my latex rendering plugin here: https://marketplace.atlassian.com/plugins/com.tensixtwo.conf.latexmath

      It implements a latex macro that functions like the one in this plugin, plus a bunch of enhanced functionality, mostly for displaying math and scientific formulae.

  7. Unknown User (leonk)

    Hello Andy,

    Any chance to update Latex plugin to be compatible with Confluence 4.x?

    It's a real stopper for us.

    We can't upgrade to ver. 4 since some of our important users use this plugin ;(

    Cheers,

    Leon

    1. Hi Leon,
      Still busy I'm afraid. I'm working hard on UI for JEMH for a JIRA 5 launch in DEC. Its not likely I'll get time to look at this until the new year.

      If anyone has free time to update it for C4 I'll happily take the zip and build, just don't have spare cycles atm.

      rgds,
      Andy

      1. Unknown User (rwiskow)

        Any chance there's been some progress on this?  Or is it even on the horizon?

        C4 sounds like it would be really nice to have, but unfortunately not having LaTeX support is a blocker for us.

        1. Ive started looking at the odler confluence plugins, and have gone through migrating one. To justify ongoing maintenance, they are migrating to commercial license.

          Are you running your own instance, I wonder about OnDemand. Latex is interesting, as its a candidate for the 'remoteapps' that OnDemand will be supporting. Migrating latex to a cloud based rendering should simplify usage for a lot of people, but will pose some interesting licensing challenges.

          I will release a current 'download' confluence compatible version this month, so stay tuned.

          1. Unknown User (qzhao7)

            Andy, do you have any update regarding this plugin? We're also holding 4.0 upgrade because it's missing the LaTex capability. Thanks.

            1. Yes, with JEMH 1.0 effectively done, I'll be starting on Confluence plugins in the next week or so. I'll announce here when its available.

            2. Unknown User (tensixtwo)

              Hey, check out the latex rendering plugin here: https://marketplace.atlassian.com/plugins/com.tensixtwo.conf.latexmath

              It implements a latex macro that functions like the one in this plugin, plus a bunch of enhanced functionality, mostly for displaying math and scientific formulae.

  8. Unknown User (nick808)

    Hi - I was trying to find a latex .jar addin the addin zips I found where xml files... am I just missing something?