Streamline LaTeX usage

1 Initial Problem

The support of LaTeX code in ILIAS has a quite long history, beginning with mimetex and blahtex which are no longer supported but still documented. Currently ILIAS uses MathJax either as a JavaScript library in the browser or as a NodeJS server module.

The LaTeX support has always been implemented for dedicated places in ILIAS (e.g. test question texts). Depending on the place, different source delimiters for LaTeX code are used: [tex]…[⁄tex] or <span class=”latex”>…</span>. Unfortunately these 'official' places have never been documented. The problem comes up with the different working modes of MathJax in the browser or on the server:

• For MathJax in the browser, ILIAS converts the source delimiters of LaTeX expressions to the native delimiters of the MathJax JavaScript library. This is done at the supported places. But the native MathJax delimiters, e.g. \( and \) are additionally recognized by the Javascript library at any place of an ILIAS page.
• The MathJax server is mainly used for HTML exports and PDF generation. The server is separately called for every supported place and the resulting HTML code (SVG or PNG image) replaces the LaTeX expression on the delivered page. Only the supported places are treated this way.

In most installations, only MathJax in the browser is activated with its default native delimiters  \( and \). As a consequence, authors began to use those LaTeX expressions at many places in ILIAS, e.g. in headlines or selections of gap questions. Some of these places are not supported by the HTML standard and will not work in all browsers. The MathJax server is not able to deal with them at all, so PDF files will not render these expressions.

A former feature request proposed an extended support of Configurable Delimiters for MathJax-Service. But this would lead to an even more complicated situation. The conclusion from a feature workshop in August 2018 was that the use of LaTeX should be better controlled by ILIAS.

2 Conceptual Summary

This feature request has been reworked for ILIAS 10.

This feature aims to streamline and simplify the support of MathJax in ILIAS. Authors should know where and how they can use LaTeX expressions, and these should be rendered reliably. Several measures are proposed to achieve this goal.

2.1 Add MathJax 3 as a Dependency

MathJax is currently added as a third-party software.  It is configured with a URL in the ILIAS administration. That allows ILIAS administrators to adapt their MathJax support, but they need the MathJax CDN or must maintain a local copy themselves. This makes it difficult to compare installations and reproduce errors in the ILIAS test installation. Updates in the case of security problems are in the responsibility of local administrators.

MathJax 3 is offered as a package for NPM and should be integrated as a dependency of ILIAS. This way ILIAS can control which MathJax version is integrated and how it is configured. Security problems, such as a missing "safe" mode, can thus be solved by ILIAS updates for all installations.

Furthermore, ILIAS components that export HTML content can include MathJax in their exported archives instead of linking it from a CDN.

The port of features from MathJax 2 to MathJax 3 is well advanced. Of the  missing features listed on the MathJax website only two are of interest for ILIAS integration:

• Currently, automatic line breaking support is missing from version 3. This is a key feature to be included in a future release.
• The localization mechanism available in version 2 has not yet been incorporated into version 3, so currently MathJax v3 is available only in English. This is an important feature that will be added to MathJax v3 in a future release.

A survey in the SIG Mathe DIGITAL revealed no necessity for this features.

2.2 Simplify Delimiter Handling

So far, the individual calls of the MathJax service have parameters which LaTeX delimiters of ILIAS are converted into the expected delimiters of MathJax. However, only two are used in ILIAS:

• [tex]…[⁄tex]
• <span class="latex">...</span>

With MathJax as a dependency, ILIAS has full control over its configuration. It can define which delimiters are used and it can add the ILIAS specific delimiters in addition to the standard delimiters of MathJax. Thus, no delimiter conversion by ILIAS is needed for[tex]…[⁄tex]. MathJax just needs to be added with its configuration to the page.

<span class="latex">...</span> is created by the TinyMCE Richtext editor. This delimiter can't be used by MathJax directly because it uses HTML tags. It's conversion can be centralized in the processing of richtext content.

2.3 Control MathJax Usage on Pages

ILIAS must be able to control where LaTeX code is to be converted. MathJax offers three configuration options for this purpose:

• skipHtmlTags: default ["script", "noscript", "style", "textarea", "pre", "code"] defines HTML elements in which no processing should take place.
• ignoreHtmlClass (default: tex2jax_ignore) can be assigned as a CSS class to an element whose content should be processed.
• processHtmlClass (default: tex2jax_process) can be assigned as a CSS class to an element whose content must not be processed.

See the MathJax documentation for details.

ILIAS will by default prohibit MathJax for the whole page and only allow it in UI components that correspond to the previously supported locations.

This can lead to problems in existing platforms where native MathJax limiters have been used in many places. But it can easily be solved with a changed MathJax configuration that sets the global disabling CSS class to an empty string.

2.4 Move MathJax to the UI Framework

The table in the accordion "Processing of LaTeX in ILIAS 9" lists all the places where content with LaTeX markup is processed. So far, the MathJax service is called at these points to convert HTML and the processed HTML is passed on to the surrounding UI component.

This contradicts the aim of the UI framework to aggregate an interface from objects and only render these before delivering a page. Having MathJax as a reliable dependency available, the whole support of MathJax can be moved from the MathJax service in ILIAS to the UI framework.

On the long run dedicated UI components may be created that support MathJax. Initially, the Legacy component will get a new function that enables MathJax inside. Its renderer will then wrap the content in a <div> that sets the CSS class for processing Latex, and it will include the MathJax script on the page. The ILIAS components just need to switch their call of the MathJax service to a use of the MathJax enhanced Legacy component (see technical details).

2.5 Move Server-Side Rendering and Special Configurations to a Plugin

Changing the MathJax support from a third-party tool to a standard functionality of ILIAS gives the great opportunity to use a well-defined configuration, e.g. for support of assistive technology. But this means that former individual configurations should no longer be supported by the core.

Furthermore, a server-side rendering can’t be supported by the ILIAS standard since this would require the maintenance of a MathJax server solution by the ILIAS core. The current description of how to set up a MathJax server refers to packages that are no longer maintained.

A survey in the SIG Mathe DIGITAL was carried out to find out how often this is used. 13 members of the SIG took part in the survey.

• MathJax in the browser is used by four with the standard CDN URL and by three with a local URL. Only one has a special configuration.
• A MathJax server is used by one for display in the browser and by four for HTML exports or PDF generation.
• Three answered that Latex is heavily used on more than the officially supported places.

This was discussed in a SIG Mathe DIGITAL meeting on July 19, 2024. As a conclusion the ILIAS core can be restricted to the standard case, if a simple solution for local tweaks is possible. This can be supported with a MathJax related plugin that independently provides the following functions:

• enable Latex processing on the entire page so that content with Latex in unintended places continues to look as before,
• change the configuration and the loaded components of MathJax so that, for example, SVG is generated instead of HTML,
• call a MathJax 3 server for rendering Latex expressions. This can speed up the display of Latex in browsers and facilitate the server-side generation of PDF files by other plugins (e.g. for test archives.

Since MathJax is moved to the UI framework, no new plugin slot hast to be created for this purpose. The plugin can use the possibility to exchange the UI renderers. By enhancing the page renderer, a server-side rendering can process the whole page content and work in the same way as MathJax in the browser. This allows to overcome the differences between browser-side and server-side support of Latex expressions on the page.

2.6 Abandon MathJax Settings in the Administration

The configuration of MathJax can drastically be simplified. No setting is needed anymore, except a global enabling or disabling of MathJax.

When MathJax is part of the core and supported by the legacy UI component of ILIAS, its JavaScript modules will be added to all pages having Legacy content, regardless of whether they have Latex code.  Sites that haven’t configured MathJax in the past would now get it on their pages, even if their users never use Latex.

To keep the opt-in behaviour of MathJax, a general enabling switch will be added to the configuration which is read by the ILIAS setup. It will be “off” by default.

2.7 Abandon LaTeX support in Certificates

ILIAS currently allows the use of LaTeX code in certificates, but the PDF generation of certificates by the Java server of ILIAS can only handle LaTeX code that has been rendered as PNG on the server side. This is not possible by the core, if a server-side rendering of MathJax is moved to a plugin.

The benefit of using Latex in certificated is very questionable. A separate feature request Abandon LaTeX in Certificates has been created for this.

3 User Interface Modifications

3.1 List of Affected Views

MathJax may affect all screens that can contain LaTeX code (see “Processing of LaTeX in ILIAS 9):

• bibliographic entries,
• forum entries,
• glossary definitions,
• pages with content from the ILIAS page editor,
• introductory message and final statement of a test or survey,
• test and survey questions.

Their editing screens should indicate that the use of LaTeX is possible (see User Interface Details).

3.2 User Interface Details

ILIAS authors should easily recognize where and how they can enter LaTeX expressions. Richtext inputs and the ILIAS page editor already provide buttons to insert LaTeX code with their preferred delimiters. No change is needed here. Plaintext inputs and text areas for elements where LaTeX is supported should get a notice in their byline on how it should be entered.

Switching from RTE to non-RTE (either in the ILIAS administration or by changing answer options of test questions from single to multi-line) should not change the entered delimiters.

3.3 New User Interface Concepts

No new user interface elements are planned.

3.4 Accessibility Implications

Mathjax 3 offers accessibility extensions.

In ILIAS they should be configured with a sensible default. The SIG Accessibility sould be included in the process of finding the default options.

4 Technical Information

4.1 Embedding

MathJax 3 is included as a dependency in the package.json of ILIAS:

"mathjax": "^3.2.2"

In this way, it can be kept up-to-date and secure by ILIAS updates. The MathJax version used is unique and can be tested for updates.

The MathJax scripts are already compiled, but they load components. Therefore, the MathJax assets must be copied to a separate directory public\node_modules\mathjax during composer install. There are start scripts for various standard configurations, e.g. whether SVG or HTML should be generated. For the ILIAS core, tex-chtml-full.js is used, which corresponds to the recommended configuration in ILIAS 9.

The processing of MathJax in ILIAS moves from the MathJax component to the UI framework. The directory of the MathJax component is deleted.

4.2 Setup and Configuration

The previous settings for MathJax as third-party software are completely removed. An activation of MathJax is provided in the setup, so that MathJax can be omitted in platforms that do not require Latex. It is a new setting for the UI component:

"ui": { 
"mathjax_enabled": true 
},

If MathJax is activated, a file mathjax.js is included on the ILIAS page, which configures and loads MathJax. It is copied to the directory public\node_modules\mathjax as an additional asset during composer install. It sets the safe mode and sets the CSS classes to activate or deactivate a Latex rendering in parts of the page. It also defines the limiters that MathJax recognises for Latex code. By adding the delimiters from ILIAS, e.g. [tex] and [/tex], ILIAS no longer needs to convert code for MathJax.

4.3 Use in Components

All calls to ilMathJax are obsolete and will be replaced.

Latex processing is only activated by components of the UI framework. The ILIAS components (e.g. the ilPageObjectGUI) have so far only processed legacy content with Latex , which can sometimes contain complex HTML. In order to minimise the migration effort, Latex is therefore initially supported by the legacy component.

Old:

$output = ilMathJax::getInstance()->insertLatexImages($output);

New:

$output = $this->ui->renderer()->render( $this->ui->factory()->legacy($output)->withLatexEnabled());

The rendering purpose is no longer set. The output is not processed but wrapped in a <div> which sets the CSS class to activate a Latex processing by the browser script. The script is added by UI component to the page.

The display of content which is edited by TinyMCE needs a conversion of the delimiters <span class=”latex”>…</span> to [tex]…[⁄tex]. This can be done by a new function in ilRTE and be called from ilLegacyFormElementsUtil::prepareTextareaOutput. 

4.4 UI Components and Rendering

There are two new interfaces for Latex supporting components in the UI Framework:

• LatexAwareComponent
• LatexAwareRenderer

Their functions can be added using traits:

• LatexAwareComponentTrait
• LatexAwareRendererTrait

The functions of the components are limited to activating and deactivating latex processing in the component.

In the renderer, the content is wrapped a <div> with the corresponding CSS class using addLatexEnabling and addLatexDisabling. The assets required for MathJax are added to the page with registerMathJaxResources. In the ILIAS core, this is the file assets/js/mathjax.js which configures and loads MathJax.

The renderer receives the information about the MathJax activation, the CSS classes and assets with the function withMathJaxConfig of the trait. This is done in the DefaultRendererFactory for renderers that implement the LatexAwareRenderer interface. A class with a MathJaxConfig interface is transferred.

When the UI framework is initialised, a MathJaxDefaultConfig is transferred. The MathJax activation is read from the ILIAS settings.

4.5 Rendering Policy

In addition to the legacy component, the LatexAwareRenderer interface is also implemented by the standard renderer of the ILIAS page. It sets a global CSS class in the <body> of the page. This class suppresses a Latex processing on the page by default and only components that have a CSS class activating it will do it.

This policy restricts the processing of Latex to the places intended by ILIAS.

4.6 MathJax Plugin

A plugin is being developed to support the ILIAS installations that would be restricted by the changes in ILIAS 10. The plugin will use the methods exchangeUIRendererAfterInitialisation and exchangeUIFactoryAfterInitialisation to process the page content shortly before delivery to the browser. This way a MathJac server can work in the same way as MathJax in the browser and render latex at all paces if that is set by the plugin.

4.7 Dynamic conversion

For pages that dynamically reload content or insert content via JavaScript, MathJax processing must be performed subsequently. The global JavaScript object of MathJax object provides a typeset function for this purpose. This function is already used in individual ILIAS JavaScript files. However, it differs between MathJax 2 and 3. This can be resricted to a MathJax 3 support.

5 Privacy

The MathJax service does not deal with personal data directly. It does, however, process the HTML content of an ILIAS page which may include personal information. The third-party library for MathJax in the browser or a configured MathJax server must be trusted (see security).

6 Security

The MathJax FAQ states:

MathJax is JavaScript code that is runs within the user’s browser, so your site’s actual content never leaves the browser while MathJax is rendering. If you are using MathJax from a CDN, it interacts with a web server to get font data and MathJax code, but this is all put together in the browser of the reader. If you have concerns about cross-site scripting, you can access the CDN service using the secure https protocol to prevent tampering with the code between the CDN and a browser; or, if you prefer, you can install MathJax on your own web server, or for off-line use. MathJax does not reference scripts from other websites. The MathJax code is, of course, open source which means that you can review it and inspect its integrity.

If MathJax is added as a dependency to ILIAS, it is delivered by the ILAS web server and no access to a CDN hast to be done. But then it must be regularly updated with new ILIAS versions and checked for security issues.

7 Contact

• Author of the Request: Neumann, Fred [fneumann]
• Maintainer: Neumann, Fred [fneumann]
• Implementation of the feature is done by: {The maintainer must add the name of the implementing developer.}

8 Funding

If you are interest in funding this feature, please add your name and institution to this list.

• TH Köln

9 Discussion

JourFixe, ILIAS [jourfixe], 25 MAR 2019 : We highly appreciate this suggestion and see it as an important step towards a streamlined handling of LaTeX support in ILIAS. Concerning the delimiters we recommend to contact the SIG Mathe Digital to find out which is the preferred one.

Sesterhenn, Fabian [sesterhenn], 30 JUNE 2020: Is there a rough estimate as to how much the implementation of this FR will cost?

10 Implementation

{The maintainer has to give a description of the final implementation and add screenshots if possible.}

Test Cases

Test cases completed at {date} by {user}

• {Test case number linked to Testrail} : {test case title}

Approval

Approved at {date} by {user}.