README.md

ember-katex

Render your math-tex formulas using KaTeX.

Demo

http://firecracker.github.io/ember-katex/

Installation

ember i ember-katex

Usage

Rendering individual formulas using {{katex-formula}}

Pass a formula as an argument.

Example

{{katex-formula
  formula = "f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi"
}}

Arguments

Argument	Type	Default	Description
formula	String		A formula to render
throwOnError	Boolean	false ⚠️	Whether to crash on parse errors
errorColor	String	'#cc0000'	A color which unsupported commands are rendered in
displayMode	Boolean	false	Whether to use the display mode. Leave it disabled for inline formulas, enable for block formulas.

Security warning

{{katex-formula}} wraps output into Ember.String.htmlSafe so that KaTeX resulting HTML gets injected into the page. If a user manages to pass malicious HTML through KaTeX own sanitization, it will be injected into the page and open your app to XSS attacks.

It is your duty to properly sanitize incoming formulas, so that no malicious HTML elements or attributes get through.

Rendering HTML with formulas using {{katex-html}} inline form

The {{katex-html}} component accepts safeHtml -- a string of HTML wrapped into Ember.String.htmlSafe(). It is your duty to properly sanitize the HTML and explicitly mark it as safe via Ember.String.htmlSafe(). If you neglect to sanitize your HTML, it will be marked

Formulas must be wrapped with \( and \) (configurable). Note: sometimes you'll need to use double backslashes, e. g. '\\(' and '\\)', in order to prevent the backslash to be treated as an escape.

Example

{
  safeHtml: Ember.computed(function () {
    return Ember.String.htmlSafe(`
      <div>
        \\(
          f(x) = \\int_{-\\infty}^\\infty \\hat f(\\xi)\\,e^{2 \\pi i \\xi x} \\,d\\xi
        \\)
      </div>
    `);
  });
}

{{katex-html safeHtml = safeHtml}}

Arguments

Argument	Type	Default	Description
safeHtml	A falsy value or String wrapped in htmlSafe()		HTML with formulas to render in place.
delimiters	Array of hashes	see	A list of delimiters to look for math.
ignoredTags	Array of strings	see	A list of DOM node types to ignore when recursing through.

Note: this comopnent leverages KaTeX in-place rendering (renderMathInElement aka auto-render). KaTeX in-place rendering does not support voluntarily crashing on errors. All parse error will be reported via browser.error and formula sources will be displayed.

Rendering HTML with formulas using {{#katex-html}} block form

Instead of passing the safeHtml argument, you can pass a Handlebars block:

{{#katex-html}}
  <div>
    \(
      f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi
    \)
  </div>
{{/katex-html}}

⚠️ You get the benefit of using Handlebars in the content passed into KaTeX, but data bindings in the content will be detached, and your content will not update dynamically, unless the {{#katex-html}} component gets torn down and a new instance is rendered (e. g. when going to another route and back). Use {{#katex-html}} block form only if your content is static, otherwise use the {{katex-html}} inline form.

⚠️ The formula and the \( \) formula markers should be within one HTML text node, otherwise KaTeX will not recognize the formula. This will not work:

{{! faulty example}}

{{#katex-html}}
  <div>
    \( {{formula}} \)
  </div>
{{/katex-html}}

You can overcome this limitation by pre-wrapping your formulas with \( and \) via a computed property or a custom helper (not included).

Rendering programmatically

This addon exposes KaTeX functions for importing:

import {
  render,
  renderToString,
  ParseError,
  renderMathInElement
} from 'katex';

License

This software is free to use under the MIT license. See the LICENSE file for license text and copyright information.

Includes fragments of code borrowed from andybluntish/ember-cli-latex-maths.