Math Engine SsKaTeX
katex.js nor any
search-and-replace script). Your HTML templates should continue referencing the KaTeX CSS. If you
host your own copy of the CSS, also keep hosting the fonts.
Requirements for running kramdown with math engine SsKaTeX:
- Ruby gem
- Ruby gem
All these requirements need to be met only if SsKaTeX is actually used.
A typical SsKaTeX configuration looks like this:
math_engine: sskatex math_engine_opts: katex_js: 'path-to-katex/katex.min.js'
The complete list of available options in
math_engine_opts follows. Most options, with the notable
katex_opts, do not affect usage nor output, but may be needed to make SsKaTeX work
with all the external parts (JS engine and KaTeX). Admins should read the security
- The path to your copy of
katex.min.js. Defaults to
'katex/katex.min.js'. For a relative path, the starting point is the current working directory.
- A dictionary with general KaTeX options such as
macros. See the KaTeX documentation for details. Use
throwOnError: falseif you want parse errors highlighted in the HTML output rather than raised as exceptions when compiling. Note that
displayModeis computed dynamically and should not be specified here.
Disabled; that last one would raise an error on first use. Which engines are actually available depends on your installation.
If js_run is not defined, the contents of the environment variable
EXECJS_RUNTIMEwill be considered instead; and if that is not defined, an automatic choice will be made. For more information, use the verbose option and consult the execjs documentation.
jsin the data directory of the
to js_dir. The default setting is
js_libs: - escape_nonascii_html.js - tex_to_html.js
Files available in the default js_dir are:
- defines a function
escape_nonascii_htmlthat converts non-ASCII characters to HTML numeric character references. Intended as postprocessing filter.
- defines a function
tex_to_html(tex, display_mode, katex_opts) that takes a LaTeX math string, a boolean display mode (
truefor block display,
falsefor inline), and a dict with general KaTeX options, and returns a string with corresponding HTML+MathML output. The implementation is allowed to set
katex_opts.displayMode. SsKaTeX applies
tex_to_htmlto each math fragment encountered. The implementation given here uses
katex.renderToStringand postprocesses the output with
- Whether to log the engine configuration. Defaults to
- For debugging. Defaults to
false. When set to something else, prints (by
The options with
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. 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.
|Usability||easy to use||all JS details configurable|
|Target users||untrusted users||trusted users|
|Target usage||web services||personal pages|
|Required Ruby gem||
|KaTeX JS/CSS/fonts||included||not included|
|Math language depends on||
|Default error handling||catches errors||throws on errors|
- 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
Duktapeis fast, but
Spidermonkeymay give better error diagnostics and backtraces.
- Web services processing kramdown input from untrusted users should not make the
sskatexgem available, as explained in the Security section.