Math support¶
Changed in version 1.8: Support for using Confluence-supported LaTeX macros.
Changed in version 1.7: SVG-generated math images requires the
sphinx.ext.imgmath
extension to be explicitly
registered to work.
Changed in version 1.4: Support both block and inlined math elements.
New in version 1.2: Initial support for math.
Mathematical notation is supported when using the Confluence builder extension. There are some limitations and special cases a user may wish to consider when trying to get the most our of their documentation/environment.
The recommended approach for rendering math in Confluence is using Sphinx’s sphinx.ext.imgmath extension. This extension renders math via LaTeX and uses either dvipng or dvisvgm to create PNG or SVG images which are published to Confluence (which requires installing a LaTeX engine alongside the Sphinx installation, such as a TeX suite/MiKTeX installation).
Math can be defined using the :math:
role or the .. math::
directive.
For example:
The Pythagorean theorem formula is :math:`a^2 + b^2 = c^2`.
The mass–energy equivalence formula:
.. math::
E = mc^2
The former case will generate math content in an inlined fashion, where the latter will generate a math block. Math defined in this way is supported on Sphinx’s standard builders with the help of other Sphinx-provided math extensions.
Recommended options for math¶
Ensure the sphinx.ext.imgmath extension is added to the documentation’s extension list:
extensions = [
'sphinx.ext.imgmath',
'sphinxcontrib.confluencebuilder',
]
If loading the sphinx.ext.imgmath extension conflicts with other builders, the extension can be optionally included using an approach such as follows (but may require additional changes depending on the environment):
import sys
extensions = [
'sphinxcontrib.confluencebuilder',
]
if any('confluence' in arg for arg in sys.argv):
extensions.append('sphinx.ext.imgmath')
The following are the recommended options to use:
imgmath_font_size = 14
imgmath_image_format = 'svg'
imgmath_use_preview = True
This configures the generated font size commonly observed on Confluence instances, hints that images are generated into SVG images (for ideal image scaling) and attempt to process the “depth” of an image to better align content alongside text.
Support for LaTeX macros for math¶
Note
This section outlines how users can take advantage of LaTeX macros enabled on their Confluence instance. The Confluence builder extension only helps forward LaTeX-generated content directly into macros. How a LaTeX macro decides to handle/render LaTeX content is up to the provider supporting the macro.
Note
Not all LaTeX macros support block and inline macros (normally, just the former).
Note
Confluence builder will attempt to support numbered equations by adding a floating label alongside a rendered math block. The variety of LaTeX macros which exist and limitations in how LaTeX macros are structured in a page may prevent the ability to perfectly align these labels alongside the rendered math content.
A stock Confluence instance does not provide LaTeX support. This is the main reason why the Confluence builder extension promotes the use of sphinx.ext.imgmath. However, if a user’s Confluence instance supports a marketplace add-on which provides LaTeX macro support, math content can instead be injected into these macros instead.
To use a LaTeX macro, the confluence_latex_macro
(ref) configuration option can be used. This
option accepts either the name of a macro to use or a dictionary of macro
options to consider (the dictionary is for more complex configurations such as
when attempting to support block-specific and inlined-specific macros). For
example, to specify the macro to use for any LaTeX content, the following
can be used:
confluence_latex_macro = 'macro-name'
If an environment supports a macro which supports block and inlined content in different macros, the following can be used:
confluence_latex_macro = {
'block-macro': 'block-macro-name',
'inline-macro': 'inline-macro-name',
'inline-macro-param': 'inline-macro-parameter', # (optional)
}
LaTeX macro names¶
What macro names to use will vary based off which macro types are installed (if any). Please see the following table for reported macro names:
Marketplace Application |
Configuration |
---|---|
Content Formatting Macros for Confluence |
confluence_latex_macro = 'latex-formatting'
|
LaTeX for Confluence |
confluence_latex_macro = 'orah-latex'
|
LaTeX Math |
confluence_latex_macro = {
'block-macro': 'mathblock',
'inline-macro': 'mathinline',
'inline-macro-param': 'body',
}
|
If a Confluence environment supports a different macro type, a user can determine the name of the macro by:
Creating a new page on the Confluence instance
Adding a LaTeX macro on the page and saving
Selecting the page’s option menu and selecting “View Storage format”
Look for the corresponding macro name inside an
ac:name
attribute (in this case, the macro’s name ismy-latex-macro
):<ac:structured-macro ac:name="my-latex-macro" ...> ... </ac:structured-macro>