diff --git a/doc/math_engine/katex.page b/doc/math_engine/katex.page index 9b404233..25872203 100644 --- a/doc/math_engine/katex.page +++ b/doc/math_engine/katex.page @@ -5,10 +5,24 @@ title: KaTeX ## Math Engine KaTeX This math engine uses [KaTeX] via the [katex rubygem][katex-gem] to convert TeX math formulas into -KaTeX HTML (using [ExecJS] under the hood). +KaTeX HTML, using [ExecJS] under the hood. This eliminates the need for client-side math-rendering +Javascript. This engine is somewhat similar to the [SsKaTeX] math engine, but easier to use and +suitable for kramdown input from untrusted users. -This eliminates the need for client-side math-rendering JavaScript. Your HTML templates still need -to include the KaTeX CSS (see the [gem's documentation][katex-gem#assets] on this). +Requirements for running kramdown with math engine KaTeX: + +- Ruby gem [`katex`][katex-gem], +- Ruby gem [`execjs`][ExecJS], +- A Javascript engine supported by ExecJS, e.g. via one of + - Ruby gem [`therubyracer`][therubyracer], + - Ruby gem [`therubyrhino`][therubyrhino], + - Ruby gem [`duktape`][duktape], + - [Node.js]. + +All these requirements need to be met only if KaTeX is actually used. Note that the [`katex` +gem][katex-gem] includes [KaTeX]'s Javascript, CSS, and fonts; those do not need to be installed +separately. Your HTML templates still need to reference the KaTeX CSS. Consult the [`katex` gem's +documentation][katex-gem#assets] on how to do that. A typical KaTeX configuration looks like this: @@ -22,8 +36,13 @@ for more information. If you need to sanitize the output, see [this example][sanitize-example] for inspiration. +[duktape]: https://github.com/judofyr/duktape.rb#duktaperb +[ExecJS]: https://github.com/rails/execjs#execjs [KaTeX]: https://khan.github.io/KaTeX/ -[ExecJS]: https://github.com/rails/execjs [katex-gem]: https://github.com/glebm/katex-ruby [katex-gem#assets]: https://github.com/glebm/katex-ruby#assets [sanitize-example]: https://github.com/thredded/thredded-markdown_katex/blob/2f5e748c90265526171a6da99557f637d2b717ec/lib/thredded/markdown_katex.rb#L48-L91 +[SsKaTeX]: sskatex.html +[therubyracer]: https://github.com/cowboyd/therubyracer#therubyracer +[therubyrhino]: https://github.com/cowboyd/therubyrhino#therubyrhino +[Node.js]: https://nodejs.org/ diff --git a/doc/math_engine/sskatex.page b/doc/math_engine/sskatex.page index 5b65b80c..5c20696e 100644 --- a/doc/math_engine/sskatex.page +++ b/doc/math_engine/sskatex.page @@ -5,8 +5,9 @@ title: SsKaTeX ## Math Engine SsKaTeX This math engine uses a server-side installation of [KaTeX] to convert TeX math formulas into -HTML+MathML. This eliminates the need for client-side math-rendering JavaScript. Consider this a -lightweight alternative to [Mathjax-Node](mathjaxnode.html). +HTML+MathML. This eliminates the need for client-side math-rendering Javascript. Consider this a +flexible for-trusted-users-only [alternative](#differences-to-the-katex-math-engine) to the [KaTeX +math engine] and a lightweight efficient alternative to [Mathjax-Node](mathjaxnode.html). Your HTML templates need no longer include Javascripts for Math (neither `katex.js` nor any search-and-replace script). Your HTML templates should continue referencing the KaTeX CSS. If you @@ -104,10 +105,41 @@ The options with `js` in their names can be used to achieve arbitrary Javascript the privileges of the kramdown process. If kramdown is part of a service that allows file uploads and user-specified math engine selection and options, the service should therefore be sandboxed (which is recommended practice), or the user-specified options filtered, or SsKaTeX kept unavailable -e.g. by not installing the `sskatex` gem. +e.g. by not installing the `sskatex` gem. Consider using the [KaTeX math engine] instead. + +### Differences to the KaTeX math engine + +Both the KaTeX and the SsKaTeX engine operate in similar ways with similar efficiency and produce +equivalent output if the underlying `katex.min.js` versions are the same. Differences are mostly in +configuration and usage scenarios. The following table gives an overview. + +| Usage aspect | KaTeX | SsKaTeX | +|:-|:-|:-| +| Usability | easy to use | all JS details configurable | +| Target users | untrusted users | trusted users | +| Target usage | web services | personal pages | +| Required Ruby gem | `katex` | `sskatex` | +| KaTeX JS/CSS/fonts | included | not included | +| Math language depends on | `katex` gem version | `katex_js` option | +| KaTeX options | in `math_engine_opts` | in `katex_opts` sub-dict | +| Default error handling | catches errors | throws on errors | + +Therefore: + +* If in doubt, try the [KaTeX math engine]. It should work out of the box. +* If you need more control and are trusted (i.e. you are allowed to run arbitrary code), try + SsKaTeX. Example uses: + - Work around issues in the current KaTeX version or in the default JS interpreter + - Try a more recent KaTeX version when you want it, and not until then + - Try interfacing with other JS-based math renderers + - Try another Javascript interpreter. E.g. `Duktape` is fast, but `Spidermonkey` may give better + error diagnostics and backtraces. +* Web services processing kramdown input from untrusted users should not make the `sskatex` gem + available, as explained in the [Security](#security) section. [duktape]: https://github.com/judofyr/duktape.rb#duktaperb [execjs]: https://github.com/rails/execjs#execjs +[KaTeX math engine]: katex.html [KaTeX]: https://khan.github.io/KaTeX/ [KaTeXopts]: https://github.com/Khan/KaTeX#rendering-options [sskatex]: https://github.com/ccorn/sskatex/