README.md (4186B)
1 # [<img src="https://khan.github.io/KaTeX/katex-logo.svg" width="130" alt="KaTeX">](https://khan.github.io/KaTeX/) [](https://travis-ci.org/Khan/KaTeX) 2 3 [](https://gitter.im/Khan/KaTeX?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 4 5 KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the web. 6 7 * **Fast:** KaTeX renders its math synchronously and doesn't need to reflow the page. See how it compares to a competitor in [this speed test](http://www.intmath.com/cg5/katex-mathjax-comparison.php). 8 * **Print quality:** KaTeX’s layout is based on Donald Knuth’s TeX, the gold standard for math typesetting. 9 * **Self contained:** KaTeX has no dependencies and can easily be bundled with your website resources. 10 * **Server side rendering:** KaTeX produces the same output regardless of browser or environment, so you can pre-render expressions using Node.js and send them as plain HTML. 11 12 KaTeX supports all major browsers, including Chrome, Safari, Firefox, Opera, and IE 8 - IE 11. A list of supported commands can be found on the [wiki](https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX). 13 14 ## Usage 15 16 You can [download KaTeX](https://github.com/khan/katex/releases) and host it on your server or include the `katex.min.js` and `katex.min.css` files on your page directly from a CDN: 17 18 ```html 19 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.7.1/katex.min.css" integrity="sha384-wITovz90syo1dJWVh32uuETPVEtGigN07tkttEqPv+uR2SE/mbQcG7ATL28aI9H0" crossorigin="anonymous"> 20 <script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.7.1/katex.min.js" integrity="sha384-/y1Nn9+QQAipbNQWU65krzJralCnuOasHncUFXGkdwntGeSvQicrYkiUBwsgUqc1" crossorigin="anonymous"></script> 21 ``` 22 23 #### In-browser rendering 24 25 Call `katex.render` with a TeX expression and a DOM element to render into: 26 27 ```js 28 katex.render("c = \\pm\\sqrt{a^2 + b^2}", element); 29 ``` 30 31 If KaTeX can't parse the expression, it throws a `katex.ParseError` error. 32 33 #### Server side rendering or rendering to a string 34 35 To generate HTML on the server or to generate an HTML string of the rendered math, you can use `katex.renderToString`: 36 37 ```js 38 var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}"); 39 // '<span class="katex">...</span>' 40 ``` 41 42 Make sure to include the CSS and font files, but there is no need to include the JavaScript. Like `render`, `renderToString` throws if it can't parse the expression. 43 44 #### Rendering options 45 46 You can provide an object of options as the last argument to `katex.render` and `katex.renderToString`. Available options are: 47 48 - `displayMode`: `boolean`. If `true` the math will be rendered in display mode, which will put the math in display style (so `\int` and `\sum` are large, for example), and will center the math on the page on its own line. If `false` the math will be rendered in inline mode. (default: `false`) 49 - `throwOnError`: `boolean`. If `true`, KaTeX will throw a `ParseError` when it encounters an unsupported command. If `false`, KaTeX will render the unsupported command as text in the color given by `errorColor`. (default: `true`) 50 - `errorColor`: `string`. A color string given in the format `"#XXX"` or `"#XXXXXX"`. This option determines the color which unsupported commands are rendered in. (default: `#cc0000`) 51 - `macros`: `object`. A collection of custom macros. Each macro is a property with a name like `\name` (written `"\\name"` in JavaScript) which maps to a string that describes the expansion of the macro. 52 53 For example: 54 55 ```js 56 katex.render("c = \\pm\\sqrt{a^2 + b^2}\\in\\RR", element, { 57 displayMode: true, 58 macros: { 59 "\\RR": "\\mathbb{R}" 60 } 61 }); 62 ``` 63 64 #### Automatic rendering of math on a page 65 66 Math on the page can be automatically rendered using the auto-render extension. See [the Auto-render README](contrib/auto-render/README.md) for more information. 67 68 ## Contributing 69 70 See [CONTRIBUTING.md](CONTRIBUTING.md) 71 72 ## License 73 74 KaTeX is licensed under the [MIT License](http://opensource.org/licenses/MIT).