A Custom Combined Component — MathJax 4.0 documentation (original) (raw)

After downloading a copy of MathJax as described in the section onGetting Things Ready, make the directory for your component andcd to that directory. We will assume the directory is calledcustom-mathjax for this discussion.

For this example, we will create a custom build that has the TeX input jax and the SVG output jax, and we will load the newcommand,ams, and configmacros extensions, but will not includerequire or autoload, so the user will not be able load any additional TeX extensions. This component also includes the contextual menu.

The Component File

Create a javascript file to house the component and call itcustom-mathjax.js. The file should contain the following code (we assume here that you used npm or pnpm to install MathJax. If not, you may need to adjust the locations in the import()commands).

custom-mathjax.js

1import {startup} from '@mathjax/src/components/js/startup/init.js'; 2import {Loader} from '@mathjax/src/js/components/loader.js'; 3import {insert} from '@mathjax/src/js/util/Options.js'; 4 5// 6// Load the components that we want to combine into one component 7// (listed in the preLoaded() call below) 8// 9import '@mathjax/src/components/js/core/core.js'; 10 11import '@mathjax/src/components/js/input/tex-base/tex-base.js'; 12import '@mathjax/src/components/js/input/tex/extensions/ams/ams.js'; 13import '@mathjax/src/components/js/input/tex/extensions/newcommand/newcommand.js'; 14import '@mathjax/src/components/js/input/tex/extensions/configmacros/configmacros.js'; 15import '@mathjax/src/components/js/ui/menu/menu.js'; 16 17// 18// Load the output jax and the code for loading its font 19// 20import {loadFont} from '@mathjax/src/components/js/output/svg/svg.js'; 21 22// 23// Load speech-generation code 24// 25import '@mathjax/src/components/js/a11y/util.js'; 26 27// 28// Mark the components that you have loaded 29// 30Loader.preLoaded( 31 'loader', 'startup', 32 'core', 33 'input/tex-base', 34 '[tex]/ams', 35 '[tex]/newcommand', 36 '[tex]/configmacros', 37 'output/svg', 38 'ui/menu' 39); 40 41// 42// Update the configuration's mathjax and sre paths and add the loaded TeX packages 43// 44insert(MathJax.config, { 45 loader: {paths: {mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@4'}}, 46 options: {worker: {path: https://cdn.jsdelivr.net/npm/mathjax@4/sre'}}, 47 tex: { 48 packages: {'[+]': ['ams', 'newcommand', 'configmacros']} 49 } 50}); 51 52// 53// Mark the MathJax version being used for this combined configuration 54// 55Loader.saveVersion('custom-mathjax.js'); 56 57// 58// Do the normal startup operations 59// 60loadFont(startup, true);

This loads the various components that we want to include in the combined component, including the standard startup code so that the usual startup process is included.

Note

This file uses ES6 import commands to load the MathJax modules. It is possible to use ES5 require() calls instead, if you wish. For example,

import {startup} from '@mathjax/src/components/js/startup/init.js';

could be replaced by

const {startup} = require('@mathjax/src/components/js/startup/init.js');

and similarly for the other import commands. Note that the MathJax package.json file is set up to route@mathjax/src/js to the MathJax mjs directory when used in an import command, and to the cjs directory when used in arequire() statement, so you can use the same path in either case. Similarly @mathjax/src/components/js maps either to thecomponents/mjs or components/cjs directory based on whetherimport or require() is used.

Line 25 causes the accessibility tools to be included in this combined component. For situations where these are not needed, leaving out lines 22 through 25 would mean that they would not be bundled into this component; but because the ui/menu component is included, its default menu settings would cause the accessibility components to be loaded individually at run time. To prevent that, you would need to change lines 46 to 50 to

insert(MathJax.config, { loader: {paths: {mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@4'}}, tex: { packages: {'[+]': ['ams', 'newcommand', 'configmacros']} }, options: { enableSpeech: false, enableBraille: false, menuOptions: { settings: { enrich: false, } } }, }, false);

This turns off semantic enrichment, and disables speech and Braille generation.

Lines 45 and 56 hard codes the path to the location where MathJax components are stored and where to get the webworker code for speech generation; these would override those settings if they were part of the MathJax configuration set by the page that loads this combined component. Similarly, the accessibility settings in the code snipped above would override any settings made in the web page, and the three TeX packages would always be included, even if the MathJax configuration from the apge explicitly removed them. This is because the changes made by the insert() command are made after the page configuration is moved to MathJax.config (which occurs during the first import at line 1), so these override the page settings.

It is possible to not overwrite these values, though it requires an extra configuration file that you import before the other importcommands. (In the case where you are using require() rather thanimport, you can put this code above the first require() incustom-mathjax.js rather than using a separate file.)

If you create the file custom-mathjax-config.js given below:

custom-mathjax-config.js

1import {insert} from '@mathjax/src/js/util/Options.js'; 2 3const GLOBAL = typeof window === 'undefined' ? global : window; 4 5GLOBAL.MathJax = insert({ 6 loader: { 7 paths: { 8 mathjax: 'https://cdn.jsdelivr.net/npm/@mathjax@4', 9 } 10 }, 11 tex: { 12 packages: ['base', 'ams', 'newcommand', 'configmacros'], 13 }, 14 // 15 // Uncomment this options block if you are NOT including the 16 // accessibility extensions in the combined component. 17 // 18 /* 19 options: { 20 enableSpeech: false, 21 enableBraille: false, 22 menuOptions: { 23 settings: { 24 enrich: false, 25 } 26 }, 27 }, 28 */ 29}, GLOBAL.MathJax || {}, false);

Here, we obtain the insert() function from theutil/Options file, which combines user configurations with default ones, and use it to set the global MathJax configuration variable to our default configuration with the user’s MathJaxvalues, if any, merged in. We don’t have to set theworker.path in this case, since it is determined from themathjax path that we have already set. (We needed to do it above because the worker path was set using the original default value of the mathjax path, not the new on at line 45.)

If you are removing the accessibility extensions from the combined component (by not importing components/js/a11y/util.js), uncomment the options block of the configuration to prevent the menu extension from loading them individually at run time.

Once this file is created, import it before any other imports, and remove the original lines 41 to 50, along with the import command that obtains the insert function. That should leave you with the following:

custom-mathjax.js

1import './custom-mathjax-config.js'; 2import {startup} from '@mathjax/src/components/js/startup/init.js'; 3import {Loader} from '@mathjax/src/js/components/loader.js'; 4 5// 6// Load the components that we want to combine into one component 7// (listed in the preLoaded() call below) 8// 9import '@mathjax/src/components/js/core/core.js'; 10 11import '@mathjax/src/components/js/input/tex-base/tex-base.js'; 12import '@mathjax/src/components/js/input/tex/extensions/ams/ams.js'; 13import '@mathjax/src/components/js/input/tex/extensions/newcommand/newcommand.js'; 14import '@mathjax/src/components/js/input/tex/extensions/configmacros/configmacros.js'; 15import '@mathjax/src/components/js/ui/menu/menu.js'; 16 17// 18// Load the output jax and the code for loading its font 19// 20import {loadFont} from '@mathjax/src/components/js/output/svg/svg.js'; 21 22// 23// Load speech-generation code 24// 25import '@mathjax/src/components/js/a11y/util.js'; 26 27// 28// Mark the components that you have loaded 29// 30Loader.preLoaded( 31 'loader', 'startup', 32 'core', 33 'input/tex-base', 34 '[tex]/ams', 35 '[tex]/newcommand', 36 '[tex]/configmacros', 37 'output/svg', 38 'ui/menu' 39); 40 41// 42// Mark the MathJax version being used for this combined configuration 43// 44Loader.saveVersion('custom-mathjax.js'); 45 46// 47// Do the normal startup operations 48// 49loadFont(startup, true);

This will allow the page that loads your combined configuration file to have full control over the MathJax configuration.

The Component Configuration File

Next, create a file config.json that includes the following:

config.json

{ "webpack": { "name": "custom-mathjax", "dist": "." } }

This file gives the name that will be used for this component (custom-mathjax in this case), and where to put the webpacked file ("." means the directory containing the config.json file). When the directory is the same as the one containing the component file, the packed component file will end in .min.js rather than just.js.

Most of the real work is done by the@mathjax/src/components/webpack.config.mjs file, which will be called automatically by the commands in the following section.

Building the Component

Once these files are created, you are ready to build the component. First, make sure that you have obtained the needed tools as described in Getting Things Ready above. Then you should be able to use the command

node ../node_modules/@mathjax/src/components/bin/makeAll

to process your custom build. You should end up with a filecustom-mathjax.min.js in the directory with the other files.

Note

If you have changed the import commands to require(), then you will need to use the command

node ../node_modules/@mathjax/src/components/bin/makeAll --cjs

in order to tell makeAll to use MathJax’swebpack.config.cjs file rather than the webpack.config.mjsone.

If you put the custom-mathjax.min.js file somewhere on your web server, you can load it into your web pages in place of loading MathJax from a CDN. This file will include all that you need to run MathJax on your pages. Just add

to your page and you should be in business (adjust the URL to point to wherever you have placed the custom-mathjax.min.js file).