MathJax Configuration

Summary

MathJax is an open-source JavaScript display engine for LaTeX, MathML, and AsciiMath notations that works in all modern browsers. It will allow you to write and display mathematical notation on web browsers. MathJax can generate output in several formats, including HTML with CSS styling, or scalable vector graphics (SVG). For more information about MathJax, you can find in the following page.


Accessing MathJax

There are two options on how to access MathJax configurations:

  • By clicking the Configure button for the add-on in the Manage add-ons UI in Confluence after installation. Then select the MathJax tab.

     

  • An alternative option is to select Latex Configurations from the side Navigation bar in the Confluence Administrator section.

Configurations

Configuration page since 1.7.9 version

Internet (CDN)

since 1.7.8 We have implemented the following changes:

  • Added Allowlist restrictions for Data Center Compliance - CDN’s are explicity required to be allowed on the Confluence Allowlist via Allow incoming.

  • Added Error messages in relation to restricted CDN - An error message will be rendered instead of mathjax render due to using a restricted CDN.

A new lozenge under is Allowed heading will indicate whether the CDN is allowed or restricted.

  • VALID if the CDN is appropriately allowed

  • INVALIDif the CDN URL is restricted.

Please see https://confluence.atlassian.com/doc/configuring-the-allowlist-381255821.html for more information on the confluence allowlist. .

Please ensure that the CDN used is allowed on your allowlist. For jsdelivr CDN you will need to use regular expression type on your allowlist an use a similar regexp for example:

https\:\/\/cdn.jsdelivr.net\/npm\/mathjax\@3.2.2\/es5\/tex-mml\-svg.min.js

Ensure that the CDN is allowed with appropriate permissions, specifically Allow incoming as shown below:

 

since 1.7.5 We have implemented the following changes:

  • Reduced MathJax resource options - only available Bundled Resources and Internet (CDN)

  • Defaults settings - are set to use Bundled Resources

Configuration page since 1.7.5 version

Bundled Resources

This option will use bundled resources to render MathJax macros. For the first time installing the add-on, bundled resources option will enable by default, which means that after install, you do not need to address any further configuration but use it right away.

Internet (CDN)

The Internet option will give the ability to choose one of the provided CDN’s and corresponding version. Once the CDN and version are selected and saved; below in the table appears full generated URL pointing to the external JS file, which will be accessed during displaying the macro in the Space page. If the bundled resources option is enabled, then Internet (CDN) will indicate INACTIVe status otherwise active

Configuration page prior to 1.7.5 version

Defaults

After the Latex add-on will be installed, MathJax configurations will have default pre-configured settings. These will allow you to use MathJax engine without additional configurations to render the macros.

Default settings:

  • Option - Internet (CDN)

  • CDN - Cloudflare

  • Version - 3.1.2

If needed the default MathJax settings can be changed by configuring one of the following options:

Local Network

The Local Network option requires the actual MathJax JS file to be located on the local server. Then in the MathJax Path field requires a full path to the stored JS file on the local network. Please note the following two points:

Allowlist

The Allowlist functionality can be disabled, however we strongly recommend to keep it functional for security purposes which will prevent saving an incorrect URL path.

Base URL

E.g. if Confluence instance is configured to be accessed via HTTPS protocol then the according to local network needs to configured to use the same protocol, otherwise, it will not allow to saving the local network URL path.

Internet (CDN)

The Internet option will give the ability to choose one of the provided CDN’s and corresponding version. Once the CDN and version are selected and saved; below in the table appears full generated URL pointing to the external JS file, which will be accessed during displaying the macro in the Space page.

Local File

Local file option gives the ability to upload the actual MathJax JS file and to be stored under Confluence-home directory > shared-home > latex-mathjax. It will create and store the JS file content in the file named ppl-mathjax.js. Once the file is uploaded successfully; the info of that file will appear in the table indicating the original file name, size, uploaded date and it will give the ability to delete the file.

Usage

Using MathJax you have the availability to display your macro in two ways either as Block or Inline.

Inline macro

You can access inline macro in two ways either via page editor directly using a shortcut { mathjax and select inline macro

or via Other macros as per example

Then you can type your macro in the equation field and preview it by clicking the Preview button. If happy with the outcome then press Insert and the macro will be populated in the page editor:

The final result on the page:

Macro as a Block

You can access block macro in two ways either via page editor directly using a shortcut { mathjax and select block macro

or via Other macros as per example

Then in the appeared block in the page editor, you can type your macro. If you want to preview it, you can press on the block and click Edit

The final result on the page:

Combination of Inline and Block macros

In this example has been used 2 inline macros and 1 block:

result of it

 

Files

In order to obtain the actual MathJax JS files, please review the following documentation - Hosting Your Own Copy of MathJax as a guide.
Once the steps are completed to get JS files, you will be able to see different types of JS file under mathjax/es5 directory.


If decided to use any js file of type SVG (e.g. mml-svg.js/tex-svg.js etc.), then no additional settings are required, only store a single js file using either for Local Network option or Local File upload option. This is the reason as SVG type, does not require any additional fonts to be requested during rendering and displaying the macro.

In order to use any js file type of CHTML (e.g. mml-chtml.js/tex-chtml.js etc.), requires to complete additional settings as per following documentation - Make the Files Available and Fonts on Shared Servers. The reason is that any file of type CHTML requires to access additional fonts to display correctly the macros. More information about fonts.

Â