KaTeX website & documentation

.gitignore

@@ -16,3 +16,10 @@ diff.png
 /test/symgroups.pdf
 /test/screenshotter/unicode-fonts
 coverage/
+lib/core/metadata.js
+lib/core/MetadataBlog.js
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*

README.md

@@ -14,9 +14,9 @@ KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the we
 
 KaTeX supports all major browsers, including Chrome, Safari, Firefox, Opera, Edge, and IE 9 - IE 11. More information can be found on the [list of supported commands](https://khan.github.io/KaTeX/function-support.html) and on the [wiki](https://github.com/khan/katex/wiki).
 
-## Usage
+## Getting started
 
-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:
+[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:
 
 ```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">
@@ -51,127 +51,9 @@ var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}");
 
 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.
 
-#### Security
-
-Any HTML generated by KaTeX *should* be safe from `<script>` or other code
-injection attacks.
-(See `maxSize` below for preventing large width/height visual affronts,
-see `maxExpand` below for preventing infinite macro loop attacks, and
-see `allowedProtocols` below for preventing certain protocols in `\href`)
-Of course, it is always a good idea to sanitize the HTML, though you will need
-a rather generous whitelist (including some of SVG and MathML) to support
-all of KaTeX.
-
-#### 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
-`katex.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
-`&amp;`, `&lt;`, `&gt;` (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.
-
-#### Rendering options
-
-You can provide an object of options as the last argument to `katex.render` and `katex.renderToString`. Available options are:
-
-- `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`)
-- `throwOnError`: `boolean`. If `true` (the default), KaTeX will throw a `ParseError` when it encounters an unsupported command or invalid LaTeX. If `false`, KaTeX will render unsupported commands as text, and render invalid LaTeX as its source code with hover text giving the error, in the color given by `errorColor`.
-- `errorColor`: `string`. A color string given in the format `"#XXX"` or `"#XXXXXX"`. This option determines the color that unsupported commands and invalid LaTeX are rendered in when `throwOnError` is set to `false`. (default: `#cc0000`)
-- `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. Single-character keys can also be included in which case the character will be redefined as the given macro (similar to TeX active characters). *This object will be modified* if the LaTeX code defines its own macros via `\gdef`, which enables consecutive calls to KaTeX to share state.
-- `colorIsTextColor`: `boolean`. If `true`, `\color` will work like LaTeX's `\textcolor`, and take two arguments (e.g., `\color{blue}{hello}`), which restores the old behavior of KaTeX (pre-0.8.0). If `false` (the default), `\color` will work like LaTeX's `\color`, and take one argument (e.g., `\color{blue}hello`).  In both cases, `\textcolor` works as in LaTeX (e.g., `\textcolor{blue}{hello}`).
-- `maxSize`: `number`. All user-specified sizes, e.g. in `\rule{500em}{500em}`, will be capped to `maxSize` ems. If set to `Infinity` (the default), users can make elements and spaces arbitrarily large.
-- `maxExpand`: `number`. Limit the number of macro expansions to the specified number, to prevent e.g. infinite macro loops. If set to `Infinity`, the macro expander will try to fully expand as in LaTeX. (default: 1000)
-- `allowedProtocols`: `string[]`. Allowed protocols in `\href`. Use `_relative` to allow relative urls, and `*` to allow all protocols. (default: `["http", "https", "mailto", "_relative"]`)
-- `strict`: `boolean` or `string` or `function` (default: `"warn"`). If `false` or `"ignore`", allow features that make writing LaTeX convenient but are not actually supported by (Xe)LaTeX (similar to MathJax). If `true` or `"error"` (LaTeX faithfulness mode), throw an error for any such transgressions. If `"warn"` (the default), warn about such behavior via `console.warn`. Provide a custom function `handler(errorCode, errorMsg, token)` to customize behavior depending on the type of transgression (summarized by the string code `errorCode` and detailed in `errorMsg`); this function can also return `"ignore"`, `"error"`, or `"warn"` to use a built-in behavior.  A list of such features and their `errorCode`s:
-  - `"unknownSymbol"`: Use of unknown Unicode symbol, which will likely also
-    lead to warnings about missing character metrics, and layouts may be
-    incorrect (especially in terms of vertical heights).
-  - `"unicodeTextInMathMode"`: Use of Unicode text characters in math mode.
-  - `"mathVsTextUnits"`: Mismatch of math vs. text commands and units/mode.
-  A second category of `errorCode`s never throw errors, but their strictness
-  affects the behavior of KaTeX:
-  - `"newLineInDisplayMode"`: Use of `\\` or `\newline` in display mode
-    (outside an array/tabular environment).  In strict mode, no line break
-    results, as in LaTeX.
-
-For example:
+## Documentation
 
-```js
-katex.render("c = \\pm\\sqrt{a^2 + b^2}\\in\\RR", element, {
-  displayMode: true,
-  macros: {
-    "\\RR": "\\mathbb{R}"
-  }
-});
-```
-
-#### Automatic rendering of math on a page
-
-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.
-
-#### Font size and lengths
-
-By default, KaTeX math is rendered in a 1.21× larger font than the surrounding
-context, which makes super- and subscripts easier to read. You can control
-this using CSS, for example:
-
-```css
-.katex { font-size: 1.1em; }
-```
-
-KaTeX supports all TeX units, including absolute units like `cm` and `in`.
-Absolute units are currently scaled relative to the default TeX font size of
-10pt, so that `\kern1cm` produces the same results as `\kern2.845275em`.
-As a result, relative and absolute units are both uniformly scaled relative
-to LaTeX with a 10pt font; for example, the rectangle `\rule{1cm}{1em}` has
-the same aspect ratio in KaTeX as in LaTeX.  However, because most browsers
-default to a larger font size, this typically means that a 1cm kern in KaTeX
-will appear larger than 1cm in browser units.
-
-### Common Issues
-- Many Markdown preprocessors, such as the one that Jekyll and GitHub Pages use,
-  have a "smart quotes" feature.  This changes `'` to `’` which is an issue for
-  math containing primes, e.g. `f'`.  This can be worked around by defining a
-  single character macro which changes them back, e.g. `{"’", "'"}`.
-- KaTeX follows LaTeX's rendering of `aligned` and `matrix` environments unlike
-  MathJax.  When displaying fractions one above another in these vertical
-  layouts there may not be enough space between rows for people who are used to
-  MathJax's rendering.  The distance between rows can be adjusted by using
-  `\\[0.1em]` instead of the standard line separator distance.
-- KaTeX does not support the `align` environment because LaTeX doesn't support
-  `align` in math mode.  The `aligned` environment offers the same functionality
-  but in math mode, so use that instead or define a macro that maps `align` to
-  `aligned`.
-- MathJax defines `\color` to be like `\textcolor` by default; set KaTeX's
-  `colorIsTextColor` option to `true` for this behavior.  KaTeX's default
-  behavior matches MathJax with its `color.js` extension enabled.
-
-## Libraries
-
-### Angular2+
-- [ng-katex](https://github.com/garciparedes/ng-katex) Angular module to write beautiful math expressions with TeX syntax boosted by KaTeX library
-
-### React
-- [react-latex](https://github.com/zzish/react-latex) React component to render latex strings, based on KaTeX
-- [react-katex](https://github.com/talyssonoc/react-katex) React components that use KaTeX to typeset math expressions
-
-### Ruby
-
-- [katex-ruby](https://github.com/glebm/katex-ruby) Provides server-side rendering and integration with popular Ruby web frameworks (Rails, Hanami, and anything that uses Sprockets).
-
-### AsciiMath
-
-If you want to render math written in [AsciiMath](http://asciimath.org/),
-you'll need to first convert AsciiMath into LaTeX input, then call KaTeX.
-
-- [asciimath2tex](https://github.com/christianp/asciimath2tex)
-  converts AsciiMath to TeX, with KaTeX in mind
+Learn more about using KaTeX [on the website](https://khan.github.io/KaTeX)!
 
 ## Contributing
 

docs/api.md

@@ -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>'
+```

docs/autorender.md

@@ -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`.

docs/browser.md

@@ -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.

docs/cli.md

@@ -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.

docs/error.md

@@ -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
+`&amp;`, `&lt;`, `&gt;` (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.