-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
KaTeX website & documentation (#1484)
* website/docs: initial commit * Change secondaryColor * Fix index.css not being copied and included on global stylesheet * Fix stylesheet link [skip ci] * Change documentation link to API(Usage) [skip ci] * Add `Libraries` in usage [skip ci] * Remove documentation from `README.md` and add link to the site [skip ci] * Use KaTeX in the parent directory to build Markdown [skip ci] * Revise function support page. Avoid error msgs. * General edit to function support page
- Loading branch information
1 parent
83e8eac
commit 8a38035
Showing
28 changed files
with
1,838 additions
and
122 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
--- | ||
id: api | ||
title: API | ||
--- | ||
## In-browser rendering | ||
Call `katex.render` with a TeX expression and a DOM element to render into: | ||
|
||
```js | ||
katex.render("c = \\pm\\sqrt{a^2 + b^2}", element); | ||
``` | ||
|
||
To avoid escaping the backslash (double backslash), you can use | ||
[`String.raw`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/raw) | ||
(but beware that `${`, `\u` and `\x` may still need escaping): | ||
```js | ||
katex.render(String.raw`c = \pm\sqrt{a^2 + b^2}`, element); | ||
``` | ||
|
||
If KaTeX can't parse the expression, it throws a `ParseError`. See [handling errors](error.md) | ||
for configuring how to handle errors. | ||
|
||
## Server side rendering or rendering to a string | ||
To generate HTML on the server or to generate an HTML string of the rendered math, you can use `katex.renderToString`: | ||
|
||
```js | ||
var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}"); | ||
// '<span class="katex">...</span>' | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,94 @@ | ||
--- | ||
id: autorender | ||
title: Auto-render Extension | ||
--- | ||
This is an extension to automatically render all of the math inside of text. It | ||
searches all of the text nodes in a given element for the given delimiters, and | ||
renders the math in place. | ||
|
||
## Usage | ||
This extension isn't part of KaTeX proper, so the script needs to be included | ||
(via a `<script>` tag) in the page along with KaTeX itself. For example, | ||
using a CDN: | ||
|
||
```html | ||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.css" integrity="sha384-9tPv11A+glH/on/wEu99NVwDPwkMQESOocs/ZGXPoIiLE8MU/qkqUcZ3zzL+6DuH" crossorigin="anonymous"> | ||
<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.js" integrity="sha384-U8Vrjwb8fuHMt6ewaCy8uqeUXv4oitYACKdB0VziCerzt011iQ/0TqlSlv8MReCm" crossorigin="anonymous"></script> | ||
<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/contrib/auto-render.min.js" integrity="sha384-aGfk5kvhIq5x1x5YdvCp4upKZYnA8ckafviDpmWEKp4afOZEqOli7gqSnh8I6enH" crossorigin="anonymous"></script> | ||
``` | ||
|
||
Then, call the exposed `renderMathInElement` function in a script tag | ||
before the close body tag: | ||
|
||
```html | ||
<body> | ||
... | ||
<script> | ||
renderMathInElement(document.body); | ||
</script> | ||
</body> | ||
``` | ||
|
||
If you prefer to have all your setup inside the html `<head>`, | ||
you can use the following script there | ||
(instead of the one above at the end of the `<body>`): | ||
|
||
```html | ||
<head> | ||
... | ||
<script> | ||
document.addEventListener("DOMContentLoaded", function() { | ||
renderMathInElement(document.body); | ||
}); | ||
</script> | ||
... | ||
</head> | ||
``` | ||
|
||
## API | ||
This extension exposes a single function, `window.renderMathInElement`, with | ||
the following API: | ||
|
||
```js | ||
function renderMathInElement(elem, options) | ||
``` | ||
|
||
`elem` is an HTML DOM element. The function will recursively search for text | ||
nodes inside this element and render the math in them. | ||
|
||
`options` is an optional object argument that can have the same keys as [the | ||
object passed to `katex.render`](https://github.com/Khan/KaTeX/#rendering-options), | ||
in addition to two auto-render-specific keys: | ||
|
||
- `delimiters`: This is a list of delimiters to look for math. Each delimiter | ||
has three properties: | ||
|
||
- `left`: A string which starts the math expression (i.e. the left delimiter). | ||
- `right`: A string which ends the math expression (i.e. the right delimiter). | ||
- `display`: A boolean of whether the math in the expression should be | ||
rendered in display mode or not. | ||
|
||
The default value is: | ||
|
||
```js | ||
[ | ||
{left: "$$", right: "$$", display: true}, | ||
{left: "\\(", right: "\\)", display: false}, | ||
{left: "\\[", right: "\\]", display: true} | ||
] | ||
``` | ||
|
||
- `ignoredTags`: This is a list of DOM node types to ignore when recursing | ||
through. The default value is | ||
`["script", "noscript", "style", "textarea", "pre", "code"]`. | ||
|
||
- `errorCallback`: A callback method returning a message and an error stack | ||
in case of an critical error during rendering. The default uses `console.error`. | ||
|
||
The `displayMode` property of the options object is ignored, and is | ||
instead taken from the `display` key of the corresponding entry in the | ||
`delimiters` key. | ||
|
||
The same `options.macros` object (which defaults to an empty object `{}`) | ||
is passed into several calls to `katex.render`, so that consecutive equations | ||
can build up shared macros by `\gdef`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
--- | ||
id: browser | ||
title: Browser | ||
--- | ||
> KaTeX supports all major browsers, including Chrome, Safari, Firefox, Opera, Edge, and IE 9 - IE 11. | ||
## CDN(Content Delivery Network) | ||
Use CDN to deliver KaTeX to your project: | ||
|
||
```html | ||
<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.js" integrity="sha256-9uW7yW4EwdUyWU2PHu+Ccek7+xbQpDTDS5OBP0qDrTM=" crossorigin="anonymous"></script> | ||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.css" integrity="sha256-T4bfkilI7rlQXG1R8kqn+FGhe56FhZmqmp9x75Lw4s8=" crossorigin="anonymous"> | ||
``` | ||
|
||
KaTeX also provides minified versions: | ||
|
||
```html | ||
<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.js" integrity="sha256-mxaM9VWtRj1wBtn50/EDUUe4m3t39ExE+xEPyrxVB8I=" crossorigin="anonymous"></script> | ||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.css" integrity="sha256-sI/DdD47R/Sa54XZDNFjRWlS+Dv8MC5xfkqQLRh0Jes=" crossorigin="anonymous"> | ||
``` | ||
|
||
## Download & Host Things Yourself | ||
Download the latest version from [here](https://github.com/Khan/KaTeX/releases), | ||
copy `katex.js`, `katex.css`(or `katex.min.js` and `katex.min.css` to use minified | ||
versions) and `fonts` from `/katex`, and include like above. | ||
|
||
## Bundler | ||
Use [`Node.js` package managers](node.md) to install KaTeX and require it in your | ||
project. Then bundle using bundlers like [webpack](https://webpack.js.org/) or | ||
[rollup.js](https://rollupjs.org/). Note that you have to bundle the stylesheet(`katex.css`) | ||
or include it manually. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
--- | ||
id: cli | ||
title: CLI | ||
--- | ||
|
||
KaTeX installed [using Node.js package managers](node.md) comes with a built-in CLI | ||
which can be used to render TeX to HTML from the command line. By default, CLI will | ||
take the input from `stdin`. | ||
|
||
```bash | ||
npx katex | ||
``` | ||
|
||
> Above uses the `npx` command to run the locally installed executable. | ||
You can execute with the relative path: `./node_modules/.bin/katex` | ||
|
||
> To use CLI from local clone, you need to build the project first by | ||
running `npm run dist` | ||
|
||
# Usage | ||
|
||
## `-d, --display-mode` | ||
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. [false] | ||
|
||
## `-t, --no-throw-on-error` | ||
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. [true] | ||
|
||
## `-c color, --error-color color` | ||
A color string given in the format 'rgb' or 'rrggbb'. This option determines the | ||
color which unsupported commands are rendered in. [#cc0000] | ||
|
||
## `-b, --color-is-text-color` | ||
Makes \color behave like LaTeX's 2-argument \textcolor, instead of LaTeX's | ||
one-argument \color mode change. [false] | ||
|
||
## `-u, --unicode-text-in-math-mode` | ||
Add support for unicode text characters in math mode. [false] | ||
|
||
## `-s size, --max-size size` | ||
If non-zero, all user-specified sizes, e.g. in \rule{500em}{500em}, will be capped | ||
to maxSize ems. Otherwise, elements and spaces can be arbitrarily large [0] | ||
|
||
## `-m macro:expansion, --macro macro:expansion` | ||
A custom macro. Each macro is a property with a name like \name which maps to a | ||
string that describes the expansion of the macro. [] | ||
|
||
## `-f path, --macro-file path` | ||
Read macro definitions from the given file. | ||
|
||
## `-i path, --input path` | ||
Read LaTeX input from the given file. | ||
|
||
## `-o path, --output path` | ||
Write html output to the given file. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
--- | ||
id: error | ||
title: Handling Errors | ||
--- | ||
If KaTeX encounters an error (invalid or unsupported LaTeX) and `throwOnError` | ||
hasn't been set to `false`, then it will throw an exception of type | ||
`ParseError`. The message in this error includes some of the LaTeX | ||
source code, so needs to be escaped if you want to render it to HTML. | ||
|
||
In particular, you should convert `&`, `<`, `>` characters to | ||
`&`, `<`, `>` (e.g., using `_.escape`) | ||
before including either LaTeX source code or exception messages in your | ||
HTML/DOM. (Failure to escape in this way makes a `<script>` injection | ||
attack possible if your LaTeX source is untrusted.) | ||
|
||
Alternatively, you can set `throwOnError` to `false` to use built-in behavior | ||
of rendering the LaTeX source code with hover text stating the error. |
Oops, something went wrong.