From ea1a226e206059e32de063044821d71e35bcd81f Mon Sep 17 00:00:00 2001 From: ylemkimon Date: Sat, 11 Aug 2018 09:21:36 +0900 Subject: [PATCH] Improve examples, add defer, async, and pre- loading KaTeX (#1580) * Wrap `katex.render` examples with try...catch * Add starter template with defer in README.md * Update documentation to use `defer` and `onload` * Add documentation on async and pre loading KaTeX * Use sha384 for SRI * Revise wording according to comments * Minor changes * Fix article --- README.md | 77 +++++++++++++++++++++++++--------------------- docs/api.md | 29 ++++++++++++----- docs/autorender.md | 46 +++++++++++++-------------- docs/browser.md | 25 ++++++++++++--- docs/error.md | 31 ++++++++++++++----- 5 files changed, 131 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index d9bc1151..4f1fceaf 100644 --- a/README.md +++ b/README.md @@ -20,56 +20,63 @@ Try out KaTeX [on the demo page](https://khan.github.io/KaTeX/#demo)! ## Getting started -[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: +### Starter template ```html - - -``` + + + + + -#### 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); -``` - -If KaTeX can't parse the expression, it throws a `katex.ParseError` error. - -#### Rendering expressions in text elements - -To automatically render math in text elements, include the [auto-render script](https://khan.github.io/KaTeX/docs/autorender.html) `contrib/auto-render.min.js`, or via CDN: - -```html - -```` - -Then, call the `renderMathInElement` function with a DOM element containing expressions in a script tag before the closing body tag: - -```html - + + + ... - - + ``` -See [Auto-render Extension](https://khan.github.io/KaTeX/docs/autorender.html) for more details. +You can also [download KaTeX](https://github.com/khan/katex/releases) and host it yourself. -#### Server side rendering or rendering to a string +For details on how to configure auto-render extension, refer to [the documentation](https://khan.github.io/KaTeX/docs/autorender.html). -To generate HTML on the server or to generate an HTML string of the rendered math, you can use `katex.renderToString`: +### API + +Call `katex.render` to render a TeX expression directly into a DOM element. +For example: ```js -var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}"); +katex.render("c = \\pm\\sqrt{a^2 + b^2}", element, { + throwOnError: false +}); +``` + +Call `katex.renderToString` to generate an HTML string of the rendered math, +e.g., for server-side rendering. For example: + +```js +var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}", { + throwOnError: false +}); // '...' ``` -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. +Make sure to include the CSS and font files in both cases. +If you are doing all rendering on the server, there is no need to include the +JavaScript on the client. -## Documentation +The examples above use the `throwOnError: false` option, which renders invalid +inputs as the TeX source code in red (by default), with the error message as +hover text. For other available options, see the +[API documentation](https://khan.github.io/KaTeX/docs/api.html), +[options documentation](https://khan.github.io/KaTeX/docs/options.html), and +[handling errors documentation](https://khan.github.io/KaTeX/docs/error.html). + +## Demo and Documentation Learn more about using KaTeX [on the website](https://khan.github.io/KaTeX)! diff --git a/docs/api.md b/docs/api.md index 6c1f4a04..ff040141 100644 --- a/docs/api.md +++ b/docs/api.md @@ -6,23 +6,38 @@ title: API 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); +katex.render("c = \\pm\\sqrt{a^2 + b^2}", element, { + throwOnError: false +}); ``` 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); +katex.render(String.raw`c = \pm\sqrt{a^2 + b^2}`, element, { + throwOnError: false +}); ``` -If KaTeX can't parse the expression, it throws a `katex.ParseError` by default. -See [handling errors](error.md) for configuring how to handle errors. - -## Server side rendering or rendering to a string +## 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}"); +var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}", { + throwOnError: false +}); // '...' ``` + +## Handling errors + +The examples above use the `throwOnError: false` option, which renders invalid +inputs as the TeX source code in red (by default), with the error message as +hover text. Without this option, invalid LaTeX will cause a +`katex.ParseError` exception to be thrown. See [handling errors](error.md). + +## Configuring KaTeX + +The last argument to `katex.render` and `katex.renderToString` can contain +[a variety of rendering options](options.md). diff --git a/docs/autorender.md b/docs/autorender.md index dbb402c3..5c1c22fc 100644 --- a/docs/autorender.md +++ b/docs/autorender.md @@ -13,36 +13,34 @@ using a CDN: ```html - - + + ``` -Then, call the exposed `renderMathInElement` function in a script tag -before the close body tag: +> Above, the [`defer` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes) +indicates that the script doesn't need to execute until the page has loaded, +speeding up page rendering; and the `onload` attribute calls +`renderMathInElement` once the auto-render script loads. + +Alternatively, you can call the `renderMathInElement` when (or after) the +[`DOMContentLoaded` event](https://developer.mozilla.org/ko/docs/Web/Reference/Events/DOMContentLoaded) +fires on the document or in another deferred script. +This approach is useful for specifying or computing options, or if you don't +want to use a `defer` or `onload` attribute. +For example: ```html - - ... - - -``` - -If you prefer to have all your setup inside the html ``, -you can use the following script there -(instead of the one above at the end of the ``): - -```html - - ... - + + - ... - + ``` ## API diff --git a/docs/browser.md b/docs/browser.md index 4844cb5c..aae84593 100644 --- a/docs/browser.md +++ b/docs/browser.md @@ -8,17 +8,34 @@ title: Browser Use CDN to deliver KaTeX to your project: ```html - - + + ``` KaTeX also provides minified versions: ```html - - + + ``` +> The loading of scripts are [deferred using `defer` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes) +to speed up page rendering. The `katex` object will be available after +[`DOMContentLoaded` event is fired on the `document`](https://developer.mozilla.org/ko/docs/Web/Reference/Events/DOMContentLoaded). +If you do not use `defer`, `katex` object will be available after corresponding +`script` tag. + +> If KaTeX is not used immediately or not critical, it is possible to load KaTeX +asynchronously. Add [`async` attribute](https://developer.mozilla.org/en/HTML/Element/script#Attributes) +to `script` and use [`rel="preload"` and `onload` attribute](https://github.com/filamentgroup/loadCSS) +on `link`. + +> You can prefetch KaTeX fonts to prevent FOUT or FOIT. Use [Web Font Loader](https://github.com/typekit/webfontloader) +or add [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content) +to `head`. (Note that only few browsers [support `rel="preload"`](https://caniuse.com/#feat=link-rel-preload) +and they all support WOFF2 so preloading WOFF2 fonts is enough.) You can use +Chrome DevTools Network panel or similar to find out which fonts are used. + ## Download & Host Things Yourself Download a [KaTeX release](https://github.com/Khan/KaTeX/releases), copy `katex.js`, `katex.css` diff --git a/docs/error.md b/docs/error.md index 9502fc91..4ea5aa4a 100644 --- a/docs/error.md +++ b/docs/error.md @@ -3,15 +3,32 @@ 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 -`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. +hasn't been set to `false`, then `katex.render` and `katex.renderToString` +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. For example: + +```js +try { + var html = katex.renderToString(texString); + // '...' +} catch (e) { + if (e instanceof katex.ParseError) { + // KaTeX can't parse the expression + html = ("Error in LaTeX '" + texString + "': " + e.message) + .replace(/&/g, "&").replace(//g, ">"); + } else { + throw e; // other error + } +} +``` 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 `