Important: This repo and gem are unmaintained! If you are interested in maintaining, please contact me at firstname.lastname@example.org.
kramdown math engine for conversion to HTML
Note: Until kramdown version 2.0.0 this math engine was part of the kramdown distribution.
gem install kramdown-math-sskatex
require 'kramdown' require 'kramdown-math-sskatex' Kramdown::Document.new(text, math_engine: :sskatex).to_html
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
- 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: false if
you want parse errors highlighted in the HTML output rather than raised as exceptions when
compiling. Note that
displayMode is 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_RUNTIME will 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.
js in the
data directory of the
sskatex gem. There is no need to change that setting unless you want to
js_libs: - escape_nonascii_html.js - tex_to_html.js
Files available in the default js_dir are:
: defines a function
escape_nonascii_html that 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 (
true for block display,
false for 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_html to each
math fragment encountered. The implementation given here uses
postprocesses the output with
: Whether to log the engine configuration. Defaults to
false. When set to something else, logs
katex_opts. That happens only once per new configuration.
: For debugging. Defaults to
false. When set to something else, prints (by
engine initialization, immediately to
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.
Clone the git repository and you are good to go. You probably want to install
rake so that you can use the provided rake tasks.
MIT - see the COPYING file.