## File: start.rst

package info (click to toggle)
mathjax-docs 2.7+20161014-1
• area: main
• in suites: stretch
• size: 1,080 kB
• ctags: 14
• sloc: sh: 22; python: 19; makefile: 8
 file content (523 lines) | stat: -rw-r--r-- 20,576 bytes parent folder | download
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523 .. _getting-started: *************** 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 our distributed network service at cdn.mathjax.org, 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. .. _mathjax-CDN: Using the MathJax Content Delivery Network (CDN) ================================================ The easiest way to use MathJax is to link directly to the public installation available through the MathJax Content Distribution Network (CDN). When you use the MathJax 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. And since bug fixes and patches are deployed to the CDN as soon as they become available, your pages will always be up to date with the latest browser and devices. To use MathJax from our server, 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. To jump start, you accomplish the first step by putting .. code-block:: html into the  block of your document. (It can also go in the  if necessary, but the head is to be preferred.) This will load the latest version 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 :ref: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 :ref:Loading and Configuring MathJax  instructions. The use of cdn.mathjax.org is governed by its terms of service _, so be sure to read that before linking to the MathJax CDN server. .. note:: To see how to enter mathematics in your web pages, see Putting mathematics in a web page_ below. .. _secure-cdn-access: Secure Access to the CDN ------------------------ If the MathJax CDN is accessed via the address http://cdn.mathjax.org (note the missing s after http), the script is downloaded over a regular, insecure HTTP connection. This poses a security risk as a malicious third party can intercept the MathJax script and replace it. This is known as a man-in-the-middle _ attack. To prevent such attacks, one should access the MathJax CDN over a secure HTTPS connection, as demonstrated in the first example earlier. If the user wishes to use insecure HTTP to download the MathJax script if and only if the page itself is downloaded over insecure HTTP, then a protocol-relative address can be used to automatically switch between HTTP and HTTPS depending on what the current page uses: .. code-block:: html Note that this trick will not work if the page is accessed locally via file:// as it will attempt to load from file://cdn.mathjax.org instead. Putting mathematics in a web page ================================= To put mathematics in your web page, you can use :term:TeX and :term:LaTeX notation, :term:MathML notation, :term:AsciiMath notation, or a combination of all three within the same page; the MathJax configuration tells MathJax which you want to use, and how you plan to indicate the mathematics when you are using TeX/LaTeX or AsciiMath notation. The configuration file used in the examples above tells MathJax to look for both TeX, AsciiMath, and MathML notation within your pages. Other configuration files tell MathJax to use only one of these input options or one of the other output options. These three formats are described in more detail below. .. _tex-and-latex-input: TeX and LaTeX input ------------------- Mathematics that is written in :term:TeX or :term:LaTeX format is indicated using *math delimiters* that surround the mathematics, telling MathJax what part of your page represents mathematics and what is normal text. There are two types of equations: ones that occur within a paragraph (in-line mathematics), and larger equations that appear separated from the rest of the text on lines by themselves (displayed mathematics). The default math delimiters are $$...$$ and $...$ for displayed mathematics, and $...$ for in-line mathematics. Note in particular that the $...$ in-line delimiters are **not** used by default. That is because dollar signs appear too often in non-mathematical settings, which could cause some text to be treated as mathematics unexpectedly. For example, with single-dollar delimiters, "... the cost is $2.50 for the first one, and$2.00 for each additional one ..." would cause the phrase "2.50 for the first one, and" to be treated as mathematics since it falls between dollar signs. For this reason, if you want to use single-dollars for in-line math mode, you must enable that explicitly in your configuration: .. code-block:: html See the config/default.js file, or the :ref:tex2jax configuration options  page, for additional configuration parameters that you can specify for the tex2jax preprocessor, which is the component of MathJax that identifies TeX notation within the page. See the :ref:TeX and LaTeX  page for more on MathJax's support for TeX, and in particular how to deal with single dollar signs in your text when you have enabled single dollar-sign delimiters. Here is a complete sample page containing TeX mathematics (also available in the test/sample-tex.html _ file): .. code-block:: html MathJax TeX Test Page When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$ and they are $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$ Since the TeX notation is part of the text of the page, there are some caveats that you must keep in mind when you enter your mathematics. In particular, you need to be careful about the use of less-than signs, since those are what the browser uses to indicate the start of a tag in HTML. Putting a space on both sides of the less-than sign should be sufficient, but see :ref:TeX and LaTeX support  for details. If you are using MathJax within a blog, wiki, or other content management system, the markup language used by that system may interfere with the TeX notation used by MathJax. For example, if your blog uses :term:Markdown notation for authoring your pages, the underscores used by TeX to indicate subscripts may be confused with the use of underscores by Markdown to indicate italics, and the two uses may prevent your mathematics from being displayed. See :ref:TeX and LaTeX support  for some suggestions about how to deal with the problem. There are a number of extensions for the TeX input processor that are loaded by combined configuration files which include TeX in their name (e.g., TeX-AMS_CHTML). These include: - TeX/AMSmath.js, which defines the AMS math environments and macros, - TeX/AMSsymbols.js, which defines the macros for the symbols in the msam10 and msbm10 fonts, - TeX/noErrors.js, which shows the original TeX code rather than an error message when there is a problem processing the TeX, and - TeX/noUndefined.js, which prevents undefined macros from producing an error message, and instead shows the macro name in red. Other extensions may be loaded automatically when needed. .. note:: See :ref:TeX and LaTeX support  for details on the other TeX extensions that are available. .. _mathml-input: MathML input ------------ For mathematics written in :term:MathML notation, you mark your mathematics using standard $ tags, where  represents displayed mathematics and  or just [itex] represents in-line mathematics. Note that even on old browsers this will work in HTML files, not just XHTML files (MathJax works with both), and that the web page need not be served with any special MIME-type. However note that in HTML (as opposed to XHTML), you should **not** include a namespace prefix for your [itex] tags; for example, you should not use  except in an XHTML file where you have tied the m namespace to the MathML DTD by adding the xmlns:m="http://www.w3.org/1998/Math/MathML" attribute to your file's  tag. Although it is not required, it is recommended that you include the xmlns="http://www.w3.org/1998/Math/MathML" attribute on all [itex] tags in your document (and this is preferred to the use of a namespace prefix like m: above, since those are deprecated in HTML5) in order to make your MathML work in the widest range of situations. Here is a complete sample page containing MathML mathematics (also available in the test/sample-mml.html _ file): .. code-block:: html MathJax MathML Test Page When a0$, there are two solutions to ax2 + bx + c = 0 [/itex] and they are x = b ± b2 4ac 2a . [/itex]

When entering MathML notation in an HTML page (rather than an XHTML page), you should **not** use self-closing tags, but should use explicit open and close tags for all your math elements. For example, you should use .. code-block:: html rather than  in an HTML document. If you use the self-closing form, some browsers will not build the math tree properly, and MathJax will receive a damaged math structure, which will not be rendered as the original notation would have been. Typically, this will cause parts of your expression to not be displayed. Unfortunately, there is nothing MathJax can do about that, since the browser has incorrectly interpreted the tags long before MathJax has a chance to work with them. The component of MathJax that recognizes MathML notation within the page is called the mml2jax extension, and it has only a few configuration options; see the config/default.js file or the :ref:mml2jax configuration options  page for more details. .. note:: See the :ref:MathML  page for more on MathJax's MathML support. .. _asciimath-input: AsciiMath input --------------- MathJax v2.0 introduced a new input format: :term:AsciiMath notation by incorporating ASCIIMathML _. By default, you mark mathematical expressions written in this form by surrounding them in "back-ticks", i.e., .... Here is a complete sample page containing AsciiMath notation (also available in the test/sample-asciimath.html _ file): .. code-block:: html MathJax AsciiMath Test Page

When a != 0, there are two solutions to ax^2 + bx + c = 0 and they are

x = (-b +- sqrt(b^2-4ac))/(2a) .

The component of MathJax that recognizes asciimath notation within the page is called the asciimath2jax extension, and it has only a few configuration options; see the config/default.js file or the :ref:asciimath2jax configuration options  page for more details. .. note:: See the :ref:AsciiMath support  page for more on MathJax's AsciiMath support. Installing Your Own Copy of MathJax =================================== We recommend using the 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. Downloading and Installing MathJax ---------------------------------- The MathJax source code is hosted on GitHub _. To install MathJax on your own server, download the latest distribution _ and 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. .. note:: For more details (such as version control access) see :ref:the installation instructions . Configuring your copy of MathJax -------------------------------- When you include MathJax into your web pages as described below, it will load the file config/TeX-MML-AM_CHTML.js (i.e., the file named TeX-MML-AM_CHTML.js in the config folder of the main MathJax folder). This file preloads all the most commonly-used components of MathJax, allowing it to process mathematics that is in the TeX or LaTeX format, AsciiMath format, or in MathML notation. It will produce output in HTML (with CSS) to render the mathematics. There are a number of other prebuilt configuration files that you can choose from as well, or you could use the config/default.js file and customize the settings yourself. .. note:: The combined configuration files are described more fully in :ref:Common Configurations , and the configuration options are described in :ref:Configuration Options . Linking your copy of MathJax into a web page -------------------------------------------- You can include MathJax in your web page by putting .. code-block:: html in your document's  block. Here, path-to-MathJax should be replaced by the URL for the main MathJax directory, so if you have put the MathJax directory at the top level of you server's web site, you could use .. code-block:: html to load MathJax in your page. For example, your page could look like .. code-block:: html ... ... .. note:: If you have installed MathJax on a server that is in a different domain from the one serving the page that loads MathJax, be sure to read the :ref:Notes About Shared Servers  for more details. In that case, you may wish to consider using the :ref:MathJax CDN  rather than installing your own copy of MathJax. Where to go from here? ====================== If you have followed the instructions above, you should now have MathJax installed and configured on your web server, and you should be able to use it to write web pages that include mathematics. At this point, you can start making pages that contain mathematical content! You could also read more about the details of how to :ref:customize MathJax . If you are trying to use MathJax in blog or wiki software or in some other content-management system, you might want to read about :ref:using MathJax in popular platforms . If you are working on dynamic pages that include mathematics, you might want to read about the :ref:MathJax Application Programming Interface  (its API), so you know how to include mathematics in your interactive pages. If you are having trouble getting MathJax to work, you can read more about :ref:installing MathJax , or :ref:loading and configuring MathJax . Finally, if you have questions or comments, or want to help support MathJax, you could visit the :ref:MathJax community forums  or the :ref:MathJax bug tracker .