= AsciiMath plugin for Jekyll

Useful when you want to render AsciiMath markup at build time, rather than using client-side JS processing.

IMPORTANT: This plugin uses https://github.com/asciidoctor/asciimath, which as of now does not support all features of AsciiMath. Certain advanced math symbols may not be rendered correctly.

== asciimath filter

When applied to a variable, replaces AsciiMath markup between specified delimiters with MathML or HTML.

For example, Liquid markup like this:

[source,liquid]

{% assign some_variable = "$$m$$ out of $$n$$ redundancy" %} {{ some_variable | asciimath }}

…would be rendered into the following MathML (whitespace in rendering examples is added for legibility):

[source,html]

out of

redundancy

…or following HTML:

[source,html]

m

out of

n

redundancy

== How it works

This plugin uses https://github.com/asciidoctor/asciimath for converting AsciiMath into MathML and HTML, and a crude regular expression for extracting AsciiMath markup from a mass of text based on delimiters.

== Configuration

The plugin will work without any extra configuration, but you should keep in mind that it uses MathML output by default (subject to browser support) and pay attention to the delimiter setting (see below).

=== Output format

Depending on the browsers you intend to support, you may choose MathML or HTML as the output format.

[source,yaml]

asciimath_output_format: mathml

Valid choices: mathml (default), html.

NOTE: MathML rendering depends on your user agent’s support of MathML.

NOTE: HTML output works across wider range of browsers, but requires the inclusion of a CSS file (see the relevant section in this document).

=== Delimiter

Currently, only one delimiter is supported (i.e., opening delimiter must be the same as trailing delimiter).

Configure the delimiter for use with asciimath filters in your site config as follows:

[source,yaml]

asciimath_delimiter: $$

The default delimiter is $$.

NOTE: If you have jekyll-asciidoc gem process stem: markup in your sources, you may want to keep in mind that its output will use \$ as delimiter.

NOTE: Delimiter will be passed to Ruby’s Regexp.quote(), so there’s no need to quote special characters.

=== Styling

For the HTML output of asciimath filter to be rendered correctly, you have to include the relevant CSS.

The plugin automatically copies the CSS file from the asciimath gem distribution into the assets directory of your site output.

To change the path to CSS, specify the asciimath_css_dir option:

[source,yaml]

asciimath_css_path: assets/math.css

To disable this behavior, set that variable to empty string.

The default path is assets/math.css.

[IMPORTANT]

The plugin will only copy the CSS file, but it will not include it your website’s source. Add the relevant <link> in your template like this:

[source,html]

--