pelican-plugins/render_math/Readme.md

Math Render Plugin For Pelican

This plugin gives pelican the ability to render mathematics. It accomplishes this by using the MathJax javascript engine. Both LaTex and MathML can be rendered within the content.

The plugin also ensures that pelican and recognized math "play" nicely together, by ensuring Typogrify does not alter math content and summaries that get cut off are repaired.

Recognized math in the context of this plugin is either LaTex or MathML as described below.

LaTex

Anything between $...$ (inline math) and $$..$$ (displayed math) will be recognized as LaTex. In addition, anything the \begin and \end LaTex macros will also be recognized as LaTex. For example, \begin{equation}...\end{equation} would be used to render math equations with numbering.

Within recognized LaTex as described above, any supported LaTex macro can be used.

MathML

Anything between <math> and </math> tags will be recognized as MathML

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!

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 recitified in this plugin, but it requires Typogrify version 2.04 (or higher). In fact, this plugin will not work with lower versions of Typogrfrify.

Usage

Backward Compatibility

This plugin is backward compatible in the sense that it will render previous setups correctly. This is because those settings and metadata information is ignored by this version. Therefore you can remove them to neaten up your site

Templates

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

If on the other hand, you are template designer and want total control over the MathJax JavaScript, you can set the auto_insert setting to False which will cause no MathJax JavaScript to be added to the content.

If you choose this option, you should really know what you are doing. Therefore only do this if you are designing your template. There is no real advantage to to letting template logic handle the insertion of the MathJax JavaScript other than it being slightly neater.

By setting auto_insert to False, metadata with key value of mathjax will be present in all pages and articles where MathJax should be present. The template designer can detect this and then use the MATHJAXSCRIPT setting which will contain the user specified MathJax script to insert into the content.

For example, this code could be used:

{% if not MATH['auto_insert'] %}
    {% if page and page.mathjax or article and article.mathjax %}
        {{ MATHJAXSCRIPT }}
    {% endif %}
{% endif %}

Settings

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

The dictionary can be set with the following keys:

• auto_insert: controls whether plugin should automatically insert MathJax JavaScript in content that has Math. It is only recommended to set this to False if you are a template designer and you want extra control over where the MathJax JavaScript is renderd. Default Value: True
• wrap_latex: controls the tags that LaTex math is wrapped with inside the resulting html. For example, setting wrap_latex to mathjax would wrap all LaTex math inside <mathjax>...</mathjax> tags. If typogrify is set to True, then math needs to be wrapped in tags and wrap_latex will therefore default to mathjax if not set. wrap_latex cannot be set to 'math' because this tag is reserved for mathml notation. Default Value: None unless Typogrify is enabled in which case, it defaults to mathjax
• align: controls how displayed math will be aligned. Can be set to either left, right or center. Default Value: center.
• indent: if align not set to center, then this controls the indent level. Default Value: 0em.
• show_menu: a boolean value that controls whether the mathjax contextual menu is shown. Default Value: True
• process_escapes: a boolean value that controls whether mathjax processes escape sequences. Default Value: True
• latex_preview: controls the preview message users are seen while mathjax is rendering LaTex. If set to Tex, then the TeX code is used as the preview (which will be visible until it is processed by MathJax). Default Value: Tex
• color: controls the color of the mathjax rendered font. Default Value: black

For example, in settings.py, the following would make math render in blue and displaymath align to the left:

MATH = {'color':'blue','align':left}

LaTex Examples

###Inline LaTex between $..$, for example, $x^2$, will be rendered inline with respect to the current html block.

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

###Equations LaTex between \begin and \end, for example, begin{equation} x^2 \end{equation}, will be rendered centered in a new paragraph with a right justified equation number at the top of the paragraph. 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}$.

MathML Examples

The following will render the Quadratic formula:

<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"> 
  <mrow>
    <mi>x</mi>
    <mo>=</mo>
    <mfrac>
      <mrow>
        <mo>&#x2212;</mo>
        <mi>b</mi>
        <mo>&#xB1;</mo>
        <msqrt>
          <mrow>
            <msup>
              <mi>b</mi>
              <mn>2</mn>
            </msup>
            <mo>&#x2212;</mo>
            <mn>4</mn>
            <mi>a</mi>
            <mi>c</mi>
          </mrow>
        </msqrt>
      </mrow>
      <mrow>
        <mn>2</mn>
        <mi>a</mi>
      </mrow>
    </mfrac>
  </mrow>
</math>