advanced/webpack.rst
.. _web-custom-build:
################################ Making a Custom Build of MathJax ################################
MathJax provides a number of combined components that load everything you need to run MathJax with a given input and output format. Still, you might find that none of the ones we provide fully suit your needs, and that you would like to include additional components in the build, or perhaps want to include customized configuration options.
You can use the MathJax component build tools to make your own custom
component that has exactly the pieces and configuration that you
want. You can also use them to make a custom extension, for example a
TeX input extension, that takes advantage of the components already
loaded, but implements additional functionality.
These possibilities are described in :ref:custom-component below.
It is also possible to make a completely custom build of MathJax that
doesn't use the MathJax components at all, but includes direct calls
to the MathJax source files. This is described in :ref:custom-build
below.
If you wish to include MathJax as part of a larger project, you can use either of the techniques to do that, and make a webpacked file that includes your own project code as well as MathJax.
.. _getting-ready:
Your first step is to download a copy of MathJax via npm,
pnpm, or git, as described in the section on
:ref:obtain-mathjax.
If you use npm or pnpm, you may want to install the
@mathjax/src package rather than the mathjax package, since
the former includes all the source code, in both its original and
compiled forms, along with the webpacked components. If you are
only going to use the webpacked components, then installing the
mathjax package will be sufficient.
If you use git, be sure to run the commands to compile and make
the components, as listed in :ref:mathjax-git.
In either case, you should have mjs, cjs, bundle, and
components directories, either in the
node_modules/@mathjax/src directory (for npm installations) or
in the main directory (for git installations).
Your second step is to obtain the tools needed to package your custom
code using webpack. Use the commands
.. code-block:: shell
npm install webpack npm install webpack-cli npm install terser-webpack-plugin
to install webpack and its needed libraries. Once this is done,
you should be able to make the components described below. The
building instructions assume you used npm to acquire MathJax; if
you used git, then you will need to change
node_modules/@mathjax/src in the paths that include them.
.. _custom-component:
MathJax comes with a number of predefined components, and you can use
their definitions <https://github.com/mathjax/MathJax-src/tree/master/components/mjs>__ as a starting
point for your own custom component. There are also custom component
examples (with documentation) in the MathJax web demos repository <https://github.com/mathjax/MathJax-demos-web#customization>__, which are
similar to the ones described here.
There are several kinds of components you could build:
A combined component that brings together several other
components (the tex-chtml component is a combined component)
An extension component that contains what is needed for one feature and can be loaded along with other components to add that feature to MathJax.
A custom build of MathJax that uses only the pieces of MathJax that you need for a specialized setting.
We describe how you can create each of these in the links below.
.. _customized-component-examples:
.. toctree::
build/component.rst build/extension.rst build/custom.rst
|-----|