Mathjax Documentation Release 2.7
Total Page:16
File Type:pdf, Size:1020Kb
MathJax Documentation Release 2.7 Davide Cervone, Casey Stark, Robert Miner, Paul Topping, Frédéric Wang, Peter Krautzberger Apr 27, 2020 Basic Usage 1 What is MathJax? 3 2 Getting Started 5 3 Installing and Testing MathJax 13 4 Loading and Configuring MathJax 19 5 Combined Configurations 27 6 MathJax TeX and LaTeX Support 37 7 MathJax MathML Support 71 8 MathJax AsciiMath Support 75 9 MathJax Output Formats 77 10 MathJax Font Support 83 11 MathJax Localization 85 12 MathJax Safe-mode 87 13 The MathJax Community 89 14 Configuration Objects 91 15 The MathJax Processing Model 125 16 The MathJax Startup Sequence 129 17 Synchronizing your code with MathJax 133 18 Loading MathJax Dynamically 143 19 Modifying Math on the Page 147 20 Obtaining the MathML for an Expression 151 i 21 Tutorial: Extension writing 153 22 MathJax Debugging tips 161 23 MathJax-node API for NodeJS 163 24 The MathJax API 165 25 Accessibility Features 207 26 Browser Compatibility 211 27 EPUB3 Reading systems overview 213 28 MathJax Badges 215 29 Articles and Presentations 217 30 Using MathJax in popular web platforms 219 31 MathJax Frequently Asked Questions 221 32 MathJax In Use 227 33 Upgrading MathJax 233 34 Describing HTML snippets 267 35 CSS Style Objects 269 36 Localization Strings 271 37 Glossary 277 Index 279 ii MathJax Documentation, Release 2.7 MathJax is an open-source JavaScript display engine for LaTeX, MathML, and AsciiMath notation that works in all modern browsers. Basic Usage 1 MathJax Documentation, Release 2.7 2 Basic Usage CHAPTER 1 What is MathJax? MathJax is an open-source JavaScript display engine for LaTeX, MathML, and AsciiMath notation that works in all modern browsers. It was designed with the goal of consolidating the recent advances in web technologies into a single, definitive, math-on-the-web platform supporting the major browsers and operating systems, including those on mobile devices. It requires no setup on the part of the user (no plugins to download or software to install), so the page author can write web documents that include mathematics and be confident that users will be able to view it naturally and easily. One simply includes MathJax and some mathematics in a web page, and MathJax does the rest. MathJax uses web-based fonts to produce high-quality typesetting that scales and prints at full resolution, unlike mathematics included as images. MathJax can be used with screen readers, providing accessibility for the visually impaired. With MathJax, mathematics is text-based rather than image-based, and so it is available for search engines, meaning that your equations can be searchable, just like the text of your pages. MathJax allows page authors to write formulas using TeX and LaTeX notation, MathML (a World Wide Web Consortium standard for representing mathematics in XML format), or AsciiMath notation. MathJax will even convert TeX notation into MathML, so that it can be rendered more quickly by those browsers that support MathML natively, or so that you can copy and paste it into other programs. MathJax is modular, so it loads components only when necessary, and can be extended to include new capabilities as needed. MathJax is highly configurable, allowing authors to customize it for the special requirements of their web sites. Finally, MathJax has a rich application programming interface (API) that can be used to make the mathematics on your web pages interactive and dynamic. 3 MathJax Documentation, Release 2.7 4 Chapter 1. What is MathJax? CHAPTER 2 Getting Started MathJax allows you to include mathematics in your web pages, either using LaTeX, MathML, or AsciiMath notation, and the mathematics will be processed using JavaScript to produce HTML, SVG, or MathML equations for viewing in any modern browser. There are two ways to access MathJax: the easiest way is to use the copy of MathJax available from a distributed network service such as cdnjs.com, but you can also download and install a copy of MathJax on your own server, or use it locally on your hard disk (with no need for network access). All three of these are described below, with links to more detailed explanations. This page gives the quickest and easiest ways to get MathJax up and running on your web site, but you may want to read the details in order to customize the setup for your pages. 2.1 Using a Content Delivery Network (CDN) The easiest way to use MathJax is to link directly to a public installation available through a Content Distribution Network (CDN). When you use a CDN, there is no need to install MathJax yourself, and you can begin using MathJax right away. The CDN will automatically arrange for your readers to download MathJax files from a fast, nearby server. To use MathJax from a CDN, you need to do two things: 1. Link to MathJax in the web pages that are to include mathematics. 2. Put mathematics into your web pages so that MathJax can display it. There are many free CDN providers that provide copies of MathJax. Some provide “rolling releases”, i.e., links that update to the latest available version upon release. (Note that we also provide a means of obtaining the latest version automatically, described below.) • cdnjs.com (recommended) • jsdelivr.com [rolling] • unpkg.com [rolling] • rawgit.com • gitcdn.xyz 5 MathJax Documentation, Release 2.7 • raw.githack.com Warning: We retired our self-hosted CDN at cdn.mathjax.org in April, 2017. We recommend using cdnjs.com which uses the same provider. The use of cdn.mathjax.org was governed by its terms of service. To jump start using cdnjs, you accomplish the first step by putting <script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML- ,!AM_CHTML"> </script> into the <head> block of your document. (It can also go in the <body> if necessary, but the head is to be preferred.) This will load the version 2.7.7 of MathJax from the distributed server, and configure it to recognize mathematics in both TeX, MathML, and AsciiMath notation, and ask it to generate its output using HTML with CSS to display the mathematics. Warning: The TeX-MML-AM_CHTML configuration is one of the most general (and thus largest) combined configuration files. We list it here because it will quickly get you started using MathJax. It is probably not the most efficient configuration for your purposes and other combined configuration files are available. You can also provide additional configuration parameters to tailor one of the combined configurations to your needs or use our development tools to generate your own combined configuration file. More details about the configuration process can be found in the Loading and Configuring MathJax instructions. If you use the code snippet given above, you will need to change the URL whenever MathJax is updated and the version changes (otherwise, you will remain at the version you linked to). It is also possible to have MathJax select its latest version for you. To do this, use <script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-MML- ,!AM_CHTML"> </script> into the <head> block of your document. In this case, MathJax will check to see what is the most current version available, and will load that, regardless of the version you specified. That way, you can always be sure you will have the most up-to-date version of MathJax, and will not have to modify your pages as new versions are released. Note: To see how to enter mathematics in your web pages, see Putting mathematics in a web page below. 2.2 Installing Your Own Copy of MathJax We recommend using a CDN service if you can, but you can also install MathJax on your own server, or locally on your own hard disk. To do so you will need to do the following things: 1. Obtain a copy of MathJax and make it available on your server or hard disk. 2. Configure MathJax to suit the needs of your site. 3. Link MathJax into the web pages that are to include mathematics. 4. Put mathematics into your web pages so that MathJax can display it. 6 Chapter 2. Getting Started MathJax Documentation, Release 2.7 These steps are described in more detail below. 2.2.1 Downloading and Installing MathJax The MathJax source code is hosted on GitHub. To install MathJax on your own server, download the latest distribution, unpack the archive, and place the resulting MathJax folder onto your web server at a convenient location where you can include it into your web pages. For example, making MathJax a top-level directory on your server would be one natural way to do this. That would let you refer to the main MathJax file via the URL /MathJax/MathJax.js from within any page on your server. Once you have MathJax set up on your server, you can test it using the files in the MathJax/test directory. If you are putting MathJax on a server, load them in your browser using their web addresses rather than opening them locally (i.e., use an http:// URL rather than a file:// URL). When you view the index.html file, after a few moments you should see a message indicating that MathJax appears to be working. If not, check that the files have been transferred to the server completely and that the permissions allow the server to access the files and folders that are part of the MathJax directory. (Be sure to verify the MathJax folder’s permissions as well.) Check the server log files for any errors that pertain to the MathJax installation; this may help locate problems in the permission or locations of files.