Home

Awesome

Math Render Plugin For Pelican

This plugin gives pelican the ability to render mathematics. It accomplishes this by using the MathJax javascript engine.

The plugin also ensures that Typogrify and recognized math "play" nicely together, by ensuring Typogrify does not alter math content.

Both Markdown and reStructuredText is supported.

Requirements

Installation

To enable, ensure that render_math plugin is accessible. Then add the following to settings.py:

PLUGINS = ["render_math"]

Your site is now capable of rendering math math using the mathjax JavaScript engine. No alterations to the template is needed, just use and enjoy!

However, if you wish, you can set the auto_insert setting to False which will disable the mathjax script from being automatically inserted into the content. You would only want to do this if you had control over the template and wanted to insert the script manually.

Typogrify

In the past, using Typgogrify would alter the math contents resulting in math that could not be rendered by MathJax. The only option was to ensure that Typogrify was disabled in the settings.

The problem has been rectified in this plugin, but it requires at a minimum Typogrify version 2.0.7 (or higher). If this version is not present, the plugin will disable Typogrify for the entire site.

BeautifulSoup4

Pelican creates summaries by truncating the contents to a specified user length. The truncation process is oblivious to any math and can therefore destroy the math output in the summary.

To restore math, BeautifulSoup4 is used. If it is not installed, no summary processing will happen.

Load custom LaTeX macros

If you use the same macros over and over, it's a good idea to not repeat yourself defining them in multiple Markdown or reStructuredText documents. What you can do instead is tell the plugin absolute paths for text files containing macro definitions.

If the same macro name has multiple definitions, the last one is used and a warning is printed to stdout.

See below in the Usage section for examples.

Usage

Templates

No alteration is needed to a template for this plugin to work. Just install the plugin and start writing your Math.

Settings

Certain MathJax rendering options can be set. These options are in a dictionary variable called MATH_JAX in the pelican settings file.

The dictionary can be set with the following keys:

Settings Examples

Make math render in blue, displaymath align to the left and load macros from /home/user/latex-macros.tex:

macros = ['/home/user/latex-macros.tex']
MATH_JAX = {'color': 'blue', 'align': 'left', 'macros': macros}

Use the color and mhchem extensions:

MATH_JAX = {'tex_extensions': ['color.js','mhchem.js']}

Resulting HTML

Inlined math is wrapped in span tags, while displayed math is wrapped in div tags. These tags will have a class attribute that is set to math which can be used by template designers to alter the display of the math.

Markdown

This plugin implements a custom extension for markdown resulting in math being a "first class citizen" for Pelican.

###Inlined Math Math between $..$, for example, $x^2$, will be rendered inline with respect to the current html block. Note: To use inline math, there must not be any whitespace before the ending $. So for example:

###Displayed Math Math between $$..$$, for example, $$x^2$$, will be rendered centered in a new paragraph.

###Latex Macros Latex macros are supported, and are automatically treated like displayed math (i.e. it is wrapped in div tag). For example, begin{equation} x^2 \end{equation}, will be rendered in its own block with a right justified equation number at the top of the block. This equation number can be referenced in the document. To do this, use a label inside of the equation format and then refer to that label using ref. For example: begin{equation} \label{eq} X^2 \end{equation}. Now refer to that equation number by $\ref{eq}$.

reStructuredText

If there is math detected in reStructuredText document, the plugin will automatically set the math_output configuration setting to MathJax.

###Inlined Math Inlined math needs to use the math role:

The area of a circle is :math:`A_\text{c} = (\pi/4) d^2`.

###Displayed Math Displayed math uses the math block:

.. math::

  α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)