https://github.com/riboseinc/jekyll-asciimath
Jekyll plugin for rendering AsciiMath syntax within posts
https://github.com/riboseinc/jekyll-asciimath
Last synced: about 2 months ago
JSON representation
Jekyll plugin for rendering AsciiMath syntax within posts
- Host: GitHub
- URL: https://github.com/riboseinc/jekyll-asciimath
- Owner: riboseinc
- License: mit
- Created: 2020-04-11T01:58:46.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2020-05-25T19:46:09.000Z (about 5 years ago)
- Last Synced: 2025-04-05T23:32:28.423Z (about 2 months ago)
- Language: Ruby
- Size: 10.7 KB
- Stars: 0
- Watchers: 8
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.adoc
- Changelog: CHANGELOG.adoc
- License: LICENSE.txt
Awesome Lists containing this project
README
= 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]
--
m
out of
n
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 `` in your template like this:
[source,html]
--
--
====