Formula Macro

Last modified by Admin on 2017/10/05 15:08

cogInserts a mathematical formula
Developed by

XWiki Development Team

Active Installs1
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise

Installable with the Extension Manager


The formula needs is written in TeX markup and rendered as an image.


Examples of formula syntax can be seen on the Wikipedia Markup page.


  • imageType: The image format; possible values: png (default), gif, jpg
  • fontSize: "Fuzzy" sizes, corresponding to the LaTeX font sizes:
    • tiny (LaTeX:\tiny), 
    • very_small (LaTeX:\scriptsize), 
    • smaller (LaTeX:\footnotesize), 
    • small (LaTeX:\small),
    • normal (default) (LaTeX:\normalsize),
    • large (LaTeX:\large),
    • larger (LaTeX:\Large),
    • very_large (LaTeX:\LARGE),
    • huge (LaTeX:\huge),
    • extremely_huge (LaTeX:\Huge).

Inserting a formula in the wiki editor

{{formula fontSize="small"}}\sum_{n=1}^\infty\frac{1}{n^2} = \frac{\pi^2}{6}{{/formula}}

Inserting a formula in the WYSIWYG editor

Place the TeX markup corresponding to the formula in the content field of the macro insertion dialog:


Inline vs. block formula

The formula macro can be used inline, inside a paragraph, or as a standalone block. Some differences exist between the two results: just like in LaTeX, inline formulas take up less vertical space than block formulas. For example, the code

Inline, a formula looks like this: {{formula}}\sum_{n=1}^\infty\frac{1}{n^2}=\frac{\pi^2}{6}{{/formula}}, while standalone it looks like this:




Technical information

The macro uses third-party tools for generating the image corresponding to a mathematical formula. Currently, four alternatives exist:

  • one based on native system calls to latex, dvips and convert. It gives the best results from a graphical point of view, but requires the presence of external programs, and involves a slight overhead by starting new processes and working with the disk.
  • one based on MathTran as a remote service through HTTP requests. The graphic results are as good as the ones obtained by the native method. Additionally, the image contains some useful metadata: the actual formula that generated the image, the position of the baseline for proper alignment, and any errors that may have occurred while processing the request. The disadvantage of this approach is that it relies heavily on a remote server.
  • the third implementation uses SnuggleTeX and JEuclid to transform LaTeX into MathML, and then render it into images. The results are not as eye-pleasing as those obtained from LaTeX, but it is a 100% Java, self-contained solution, with no external dependencies.
  • a fourth one was introduced in XWiki 2.1, based on the public Google Chart APIs as a remote service through HTTP requests. The quality of the results is between those obtained from the native TeX system and those from SnuggleTeX. Unlike MathTran, it doesn't use a native TeX system, thus there are a few disadvantages other than the quality:
    • only block-level equations are produced
    • there's no support (yet?) for different font sizes and image formats
    • the results are not 100% in accordance with the TeX syntax (for example it does not understand root, the content between left and right is lowered)

The method used by default is the one based on native system calls. If the required tools are not available on the system, the SnuggleTeX implementation is used instead. The default formula rendering method can be configured by modifying the option macro.formula.renderer in the file WEB-INF/, with the possible values native, mathtran, snuggletex and googlecharts.


This feature is based on the Tex plugin developed by Guillaume Legris.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


Dependencies for this extension (org.xwiki.platform:xwiki-platform-formula-macro 9.8.1):

Tags: math latex
Created by Marta Girdea on 2009/08/28 19:16

Get Connected