Mercurial > repos > public > wdown

annotate katex/README.md @ 8:4a25b534c81c javascript-experiment

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add v8 engine and include katex
author Jonatan Werpers <jonatan@werpers.com>
date Wed, 17 Jun 2020 21:43:52 +0200
parents
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
1 # [<img src="https://katex.org/img/katex-logo-black.svg" width="130" alt="KaTeX">](https://katex.org/)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
2 [![npm](https://img.shields.io/npm/v/katex.svg)](https://www.npmjs.com/package/katex)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
3 [![CircleCI](https://circleci.com/gh/KaTeX/KaTeX.svg?style=shield)](https://circleci.com/gh/KaTeX/KaTeX)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
4 [![codecov](https://codecov.io/gh/KaTeX/KaTeX/branch/master/graph/badge.svg)](https://codecov.io/gh/KaTeX/KaTeX)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
5 [![Join the chat at https://gitter.im/KaTeX/KaTeX](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/KaTeX/KaTeX?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
6 [![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=KaTeX/KaTeX)](https://dependabot.com)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
7 [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/katex/badge?style=rounded)](https://www.jsdelivr.com/package/npm/katex)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
8 ![](https://img.badgesize.io/KaTeX/KaTeX/v0.11.1/dist/katex.min.js?compression=gzip)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
9
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
10 KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the web.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
11
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
12 * **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).
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
13 * **Print quality:** KaTeX's layout is based on Donald Knuth's TeX, the gold standard for math typesetting.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
14 * **Self contained:** KaTeX has no dependencies and can easily be bundled with your website resources.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
15 * **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.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
16
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
17 KaTeX is compatible with all major browsers, including Chrome, Safari, Firefox, Opera, Edge, and IE 9–11.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
18
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
19 KaTeX supports much (but not all) of LaTeX and many LaTeX packages. See the [list of supported functions](https://katex.org/docs/supported.html).
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
20
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
21 Try out KaTeX [on the demo page](https://katex.org/#demo)!
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
22
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
23 ## Getting started
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
24
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
25 ### Starter template
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
26
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
27 ```html
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
28 <!DOCTYPE html>
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
29 <!-- KaTeX requires the use of the HTML5 doctype. Without it, KaTeX may not render properly -->
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
30 <html>
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
31 <head>
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
32 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
33
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
34 <!-- The loading of KaTeX is deferred to speed up page rendering -->
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
35 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script>
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
36
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
37 <!-- To automatically render math in text elements, include the auto-render extension: -->
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
38 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
39 onload="renderMathInElement(document.body);"></script>
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
40 </head>
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
41 ...
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
42 </html>
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
43 ```
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
44
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
45 You can also [download KaTeX](https://github.com/KaTeX/KaTeX/releases) and host it yourself.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
46
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
47 For details on how to configure auto-render extension, refer to [the documentation](https://katex.org/docs/autorender.html).
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
48
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
49 ### API
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
50
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
51 Call `katex.render` to render a TeX expression directly into a DOM element.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
52 For example:
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
53
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
54 ```js
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
55 katex.render("c = \\pm\\sqrt{a^2 + b^2}", element, {
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
56 throwOnError: false
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
57 });
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
58 ```
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
59
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
60 Call `katex.renderToString` to generate an HTML string of the rendered math,
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
61 e.g., for server-side rendering. For example:
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
62
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
63 ```js
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
64 var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}", {
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
65 throwOnError: false
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
66 });
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
67 // '<span class="katex">...</span>'
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
68 ```
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
69
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
70 Make sure to include the CSS and font files in both cases.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
71 If you are doing all rendering on the server, there is no need to include the
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
72 JavaScript on the client.
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
73
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
74 The examples above use the `throwOnError: false` option, which renders invalid
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
75 inputs as the TeX source code in red (by default), with the error message as
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
76 hover text. For other available options, see the
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
77 [API documentation](https://katex.org/docs/api.html),
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
78 [options documentation](https://katex.org/docs/options.html), and
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
79 [handling errors documentation](https://katex.org/docs/error.html).
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
80
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
81 ## Demo and Documentation
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
82
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
83 Learn more about using KaTeX [on the website](https://katex.org)!
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
84
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
85 ## Contributing
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
86
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
87 See [CONTRIBUTING.md](CONTRIBUTING.md)
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
88
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
89 ## License
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
90
4a25b534c81c Add v8 engine and include katex
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
91 KaTeX is licensed under the [MIT License](http://opensource.org/licenses/MIT).