Pelican Render Math

Mon 05 September 2016
Category: meta

I occasionally tutor in math, physics and computer science, and once upon a time I actually had degrees in all three, so of course I want to be able to render math (and embed various physics and software demos) in my blog.

As a start I added the Pelican Render Math plugin.

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.

Like the pelican sitemap plugin, the render math module does not exist at pypi so to install it, I copied the render math module from my local clone of the pelican plugins into a plugins directory local to this blog.

$ cp -r ../pelican-plugins/render-math plugins

Again, that’s certainly not the hippest gittest way of handling it, and I assume it’s actually a terrible way of handling this, but it works, for now…

Settings in

Enabled the plugin

    # ...
    # ...

Configuring python

Apparently there is a conflict between how render_math and pelican summaries are created that is resolved by installing beautifulsoup4, so I installed that into my virtual env

$ pip install beautifulsoup4
Collecting beautifulsoup4
  Using cached beautifulsoup4-4.5.1-py2-none-any.whl
Installing collected packages: beautifulsoup4
Successfully installed beautifulsoup4-4.5.1

and then to get Gitlab to include beautiful soup I added it to requirements.txt which the gitlab shared runner loads up using pip.

$ echo "beautifulsoup4" >> requirements.txt


Taken from the Render Math Readme


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:

  • Relevant inline math: $e=mc^2$ (\(e=mc^2\))
  • Will not render as inline math: $40 vs $50

Displayed Math

Math between $$..$$ will be rendered “block style”, for example, $$x^2$$, will be rendered centered in a new paragraph.


Other Latex Display Math commands

The other LaTeX commands which usually invoke display math mode from text mode are supported, and are automatically treated like $$-style displayed math in that they are rendered “block” style on their own lines. 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} $.

\begin{equation}\label{xsq} x^2 \end{equation}

As we see in equation \(\ref{xsq}\)

Some more examples, taken from

a& =b+c-d\\
& \quad +e-f\\
& =g+h\\
& =i
\begin{equation}\label{xx} \begin{split} a& =b+c-d\\ & \quad +e-f\\ & =g+h\\ & =i \end{split} \end{equation}
\begin{multline} a+b+c+d+e+f\\ +i+j+k+l+m+n \end{multline}
\begin{gather} a_1=b_1+c_1\\ a_2=b_2+c_2-d_2+e_2 \end{gather}
a_1& =b_1+c_1\\
a_2& =b_2+c_2-d_2+e_2
\begin{align} a_1& =b_1+c_1\\ a_2& =b_2+c_2-d_2+e_2 \end{align}
a_{11}& =b_{11}&
a_{12}& =b_{12}\\
a_{21}& =b_{21}&
a_{22}& =b_{22}+c_{22}
\begin{align} a_{11}& =b_{11}& a_{12}& =b_{12}\\ a_{21}& =b_{21}& a_{22}& =b_{22}+c_{22} \end{align}

[this example seems to fail however, why?]

a_{11}& =b_{11}&
a_{12}& =b_{12}\\
a_{21}& =b_{21}&
a_{22}& =b_{22}+c_{22}
\begin{flalign*} a_{11}& =b_{11}& a_{12}& =b_{12}\\ a_{21}& =b_{21}& a_{22}& =b_{22}+c_{22} \end{flalign*}

Examples from

\sin A \cos B &= \frac{1}{2}\left[ \sin(A-B)+\sin(A+B) \right] \\
\sin A \sin B &= \frac{1}{2}\left[ \sin(A-B)-\cos(A+B) \right] \\
\cos A \cos B &= \frac{1}{2}\left[ \cos(A-B)+\cos(A+B) \right] \\
\begin{align*} \sin A \cos B &= \frac{1}{2}\left[ \sin(A-B)+\sin(A+B) \right] \\ \sin A \sin B &= \frac{1}{2}\left[ \sin(A-B)-\cos(A+B) \right] \\ \cos A \cos B &= \frac{1}{2}\left[ \cos(A-B)+\cos(A+B) \right] \\ \end{align*}
\begin{equation} \sqrt2x \text{ is not the same as } \sqrt{2x}. \end{equation}
\begin{equation} \sqrt2x \text{ is not the same as } \sqrt{2x}. \end{equation}
\frac{d}{dx}\left( \int_{0}^{x} f(u)\,du\right)=f(x).
\begin{equation} \frac{d}{dx}\left( \int_{0}^{x} f(u)\,du\right)=f(x). \end{equation}


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 λ)

Category: meta Tagged: pelican pelican-plugins change-log