22
33## Beautiful math in all browsers
44
5- MathJax is an open-source JavaScript display engine for LaTeX, MathML, and
6- AsciiMath notation that works in all modern browsers. It was designed with
7- the goal of consolidating the recent advances in web technologies into a
8- single, definitive, math-on-the-web platform supporting the major browsers
9- and operating systems. It requires no setup on the part of the user (no
10- plugins to download or software to install), so the page author can write
11- web documents that include mathematics and be confident that users will be
12- able to view it naturally and easily. Simply include MathJax and some
13- mathematics in a web page, and MathJax does the rest.
5+ MathJax is an open-source JavaScript display engine for LaTeX, MathML,
6+ andAsciiMath notation that works in all modern browsers. It was
7+ designed with the goal of consolidating the recent advances in web
8+ technologies into a single, definitive, math-on-the-web platform
9+ supporting the major browsers and operating systems. It requires no
10+ setup on the part of the user (no plugins to download or software to
11+ install), so the page author can write web documents that include
12+ mathematics and be confident that users will be able to view it
13+ naturally and easily. Simply include MathJax and some mathematics in
14+ a web page, and MathJax does the rest.
1415
1516Some of the main features of MathJax include:
1617
@@ -26,28 +27,164 @@ Some of the main features of MathJax include:
2627
2728- Powerful API for integration with other web applications
2829
29- See < http://www.mathjax.org/ > for additional details.
30+ See < http://www.mathjax.org/ > for additional details about MathJax,
31+ and < https://docs.mathjax.org > for the MathJax documentation.
3032
33+ ## MathJax Components
3134
32- ## Installation and Usage
35+ MathJax version 3 uses files called * components* that contain the
36+ various MathJax modules that you can include in your web pages or
37+ access on a server through NodeJS. Some components combine all the
38+ pieces you need to run MathJax with one or more input formats and a
39+ particular output format, while other components are pieces that can
40+ be loaded on demand when needed, or by a configuration that specifies
41+ the pieces you want to combine in a custom way. For usage
42+ instructions, see the [ MathJax documentation] ( https://docs.mathjax.org ) .
3343
34- The MathJax installation and usage documentation is available in a
35- separate GitHub repository at < https://github.com/mathjax/mathjax-docs > .
36- The HTML versions can now be viewed at < http://docs.mathjax.org/ > ,
37- where it is possible for you to submit corrections and modifications
38- directly to the documentation on line.
44+ Components provide a convenient packaging of MathJax's modules, but it
45+ is possible for you to form your own custom components, or to use
46+ MathJax's modules directly in a node application on a server. There
47+ are [ web examples] ( https://github.com/mathjax/MathJax-demos-web )
48+ showing how to use MathJax in web pages and how to build your own
49+ components, and [ node
50+ examples] ( https://github.com/mathjax/MathJax-demos-node ) illustrating
51+ how to use components in node applications or call MathJax modules
52+ directly.
3953
54+ ## What's in this Repository
4055
41- ## Community
56+ This repository contains only the component files for MathJax, not the
57+ source code for MathJax (which are available in a separate [ MathJax
58+ source repository] ( https://github.com/mathjax/MathJax-src/ ) ). These
59+ component files are the ones served by the CDNs that offer MathJax to
60+ the web. In version 2, the files used on the web were also the source
61+ files for MathJax, but in version 3, the source files are no longer on
62+ the CDN, as they are not what are run in the browser.
4263
43- The main MathJax website is < http://www.mathjax.org > , and it includes
44- announcements and other important information. MathJax is maintained and
45- distributed on GitHub at < http://github.com/mathjax/MathJax > . A user forum
46- for asking questions and getting assistance is hosted at Google, and the
47- bug tracker is hosted at GitHub:
64+ The components are stored in the ` es5 ` director, and are in ES5 format
65+ for the widest possible compatibility. In the future, we may make an
66+ ` es6 ` directory containing ES6 versions of the components.
67+
68+ ## Installation and Use
69+
70+ ### Using MathJax components from a CDN on the web
71+
72+ If you are loading MathJax from a CDN into a web page, there is no
73+ need to install anything. Simply use a ` script ` tag that loads
74+ MathJax from the CDN. E.g.,
75+
76+ <script id="MathJax-script" async
77+ src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
78+ </script>
79+
80+ See the
81+ [ documentation] ( https//docs.mathjax.org/en/latest/index.html#browser-components )
82+ for more details.
83+
84+ ### Hosting your own copy of the MathJax Components
85+
86+ If you want to host MathJax from your own server, you can do so by
87+ installing the ` mathjax ` package using ` npm ` and moving the ` es5 `
88+ directory to an appropriate location on your server:
89+
90+ npm install mathjax
91+ mv node_modules/mathjax/es5 <path-to-server-location>/mathjax
92+
93+ Alternatively, you can get the files via github:
94+
95+ git clone https://github.com/mathjax/MathJax.git mj-tmp
96+ mv mj-tmp/es5 <path-to-server-location>/mathjax
97+ rm -rf mj-tmp
98+
99+ Then (in either case) you can use a script tag like the following:
100+
101+ <script id="MathJax-script" async
102+ src="<url-to-your-site>/mathjax/tex-chtml.js"></script>
103+
104+ where ` <url-to-your-site> ` is replaced by the URL to the location
105+ where you moved the MathJax files above.
106+
107+ See the
108+ [ documentation] ( https://docs.mathjax.org/en/latest/web/hosting.html )
109+ for details.
110+
111+ ### Using MathJax components in a node application
112+
113+ To use MathJax components in a node application, install the ` mathjax `
114+ package:
48115
49- Bug tracker: < https://github.com/mathjax/MathJax/issues >
50- MathJax-Users Group: < http://groups.google.com/group/mathjax-users >
116+ npm install mathjax
117+
118+ and require ` mathjax ` within your application:
119+
120+ require('mathjax').init({ ... }).then((MathJax) => { ... });
121+
122+ where the first ` { ... } ` is a MathJax configuration, and the second
123+ ` { ... } ` is the code to run after MathJax has been loaded. E.g.
124+
125+ require('mathjax').init({
126+ loader: {load: ['input/tex', 'output/svg']}
127+ }).then((MathJax) => {
128+ const svg = MathJax.tex2svg('\\frac{1}{x^2-1}', {display: true});
129+ console.log(MathJax.startup.adaptor.outerHTML(svg));
130+ }).catch((err) => console.log(err.message));
131+
132+
133+ See the
134+ [ documentation] ( https//docs.mathjax.org/en/latest/index.html#server-nodejs )
135+ for more details.
136+
137+ ## Reducing the Size of the Components Directory
138+
139+ Since the ` es5 ` directory contains * all* the component files, so if
140+ you are only planning one use one configuration, you can reduce the
141+ size of the MathJax directory by removing unused components. For
142+ example, if you are using the ` tex-chtml.js ` component, then you can
143+ remove the ` tex-mml-chtml.js ` , ` tex-svg.js ` , ` tex-mml-svg.js ` ,
144+ ` tex-chtml-full.js ` , and ` tex-svg-full.js ` configurations, which will
145+ save considerable space. Indeed, you should be able to remove
146+ everything other than ` tex-chtml.js ` , and the ` input/tex/extensions ` , ` output/chtml/fonts/woff-v2 ` , ` adaptors ` , ` a11y ` , and ` sre ` directories. If you are using the results only on the web, you can remove ` adaptors ` as well.
147+
148+ If you are not using A11Y support (e.g., speech generation, or semantic enrichment), then you can remove ` a11y ` and ` sre ` as well (though in this case you may need to disable the assistive tools in the MathJax contextual menu in order to avoid MathJax trying to load them when they aren't there).
149+
150+ If you are using SVG rather that CommonHTML output (e.g., ` tex-svg.js ` rather than ` tex-chtml.js ` ), you can remove the ` output/chtml/fonts/woff-v2 ` directopry. If you are using MathML input rather than TeX (e.g., ` mml-chtml.js ` rather than ` tex-chtml.js ` ), then you can remove ` input/tex/extensions ` as well.
151+
152+
153+ ## The Component Files and Pull Requests
154+
155+ The ` es5 ` directory is generated automatically from the contents of the
156+ MathJax source repository. You can rebuild the components using the
157+ command
158+
159+ npm run make-es5 --silent
160+
161+ Note that since the contents of this repository are generated
162+ automatically, you should not submit pull requests that modify the
163+ contents of the ` es5 ` directory. If you wish to submit a modification
164+ to MathJax, you should make a pull request in the [ MathJax source
165+ repository] ( https://github.com/mathjax/MathJax-src ) .
166+
167+ ## MathJax Community
168+
169+ The main MathJax website is < http://www.mathjax.org > , and it includes
170+ announcements and other important information. A [ MathJax user
171+ forum] ( http://groups.google.com/group/mathjax-users ) for asking
172+ questions and getting assistance is hosted at Google, and the [ MathJax
173+ bug tracker] ( https://github.com/mathjax/MathJax/issues ) is hosted
174+ at GitHub.
175+
176+ Before reporting a bug, please check that it has not already been
177+ reported. Also, please use the bug tracker (rather than the help
178+ forum) for reporting bugs, and use the user's forum (rather than the
179+ bug tracker) for questions about how to use MathJax.
180+
181+ ## MathJax Resources
182+
183+ * [ MathJax Documentation] ( https://docs.mathjax.org )
184+ * [ MathJax Components] ( https://github.com/mathjax/MathJax )
185+ * [ MathJax Source Code] ( https://github.com/mathjax/MathJax-src )
186+ * [ MathJax Web Examples] ( https://github.com/mathjax/MathJax-demos-web )
187+ * [ MathJax Node Examples] ( https://github.com/mathjax/MathJax-demos-node )
188+ * [ MathJax Bug Tracker] ( https://github.com/mathjax/MathJax/issues )
189+ * [ MathJax Users' Group] ( http://groups.google.com/group/mathjax-users )
51190
52- Before reporting a bug, please check that it has not already been reported.
53- Also, please use the bug tracker for reporting bugs rather than the help forum.
0 commit comments