Pelican plugins » Math and code

These plug­ins use ex­ter­nal li­braries to pro­duce beau­ti­ful math and code ren­der­ing di­rect­ly from your reST sources.

Math

Down­load the m/math.py and la­tex2svg.py files, put them in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.math pack­age to your PLUGINS in pelicanconf.py. This plug­in as­sumes pres­ence of m.html­san­i­ty.

PLUGINS += ['m.htmlsanity', 'm.math']
M_MATH_RENDER_AS_CODE = False
M_MATH_CACHE_FILE = 'm.math.cache'

In ad­di­tion you need some La­TeX dis­tri­bu­tion in­stalled. Use your dis­tri­bu­tion pack­age man­ag­er, for ex­am­ple on Ubun­tu:

sudo apt install texlive-base texlive-latex-extra texlive-fonts-extra

The plug­in over­rides the builtin do­cu­tils math di­rec­tive and math in­ter­pret­ed text role and:

  • In­stead of re­ly­ing on MathML or Math­Jax, con­verts in­put La­TeX math for­mu­la to a SVG file, which is then em­bed­ded di­rect­ly to the page. All glyphs are con­vert­ed to paths.
  • Size is rep­re­sent­ed us­ing CSS em units so the for­mu­la fol­lows sur­round­ing text size.
  • Adds a pos­si­bil­i­ty to col­or the whole for­mu­la or parts of it us­ing col­ors that fol­low the cur­rent theme.
  • Adds a <title> con­tain­ing the orig­i­nal for­mu­la to the gen­er­at­ed <svg> el­e­ment for ac­ces­si­bil­i­ty.

Put math blocks in­to the .. math:: di­rec­tive; if you want to col­or the equa­tions, add cor­re­spond­ing CSS class via a :class: op­tion. Equa­tions sep­a­rat­ed by a blank line are pro­cessed sep­a­rate­ly.

.. math::
    :class: m-success

    \boldsymbol{A} = \begin{pmatrix}
        \frac{2n}{s_x} & 0 & 0 & 0 \\
        0 & \frac{2n}{s_y} & 0 & 0 \\
        0 & 0 & \frac{n + f}{n - f} & \frac{2nf}{n - f} \\
        0 & 0 & -1 & 0
    \end{pmatrix}
\boldsymbol{A} = \begin{pmatrix} \frac{2n}{s_x} & 0 & 0 & 0 \\ 0 & \frac{2n}{s_y} & 0 & 0 \\ 0 & 0 & \frac{n + f}{n - f} & \frac{2nf}{n - f} \\ 0 & 0 & -1 & 0 \end{pmatrix}

In­line math can be wrapped in the :math: in­ter­pret­ed text role. If you want to add ad­di­tion­al CSS class­es, de­rive a cus­tom role from it.

.. role:: math-info(math)
    :class: m-info

Quaternion-conjugated dual quaternion is :math-info:`\hat q^* = q_0^* + q_\epsilon^*`,
while dual-conjugation gives :math:`\overline{\hat q} = q_0 - \epsilon q_\epsilon`.

Quater­nion-con­ju­gat­ed du­al quater­nion is \hat q^* = q_0^* + q_\epsilon^* , while du­al-con­ju­ga­tion gives \overline{\hat q} = q_0 - \epsilon q_\epsilon .

The re­sult­ing SVG fol­lows font size of sur­round­ing text, so you can use math even out­side of main page copy:

.. button-success:: https://tauday.com/

    The :math:`\tau` manifesto

    they say :math:`\pi` is wrong

The xcolor pack­age is en­abled by de­fault to­geth­er with names match­ing CSS col­or class­es. You can use it to high­light dif­fer­ent parts of the for­mu­la:

.. math::

    \boldsymbol{A} = \begin{pmatrix}
        {\color{m-info} s_x} & 0 & 0 & {\color{m-success} t_x} \\
        0 & {\color{m-info} s_y} & 0 & {\color{m-success} t_y} \\
        0 & 0 & {\color{m-info} s_z} & {\color{m-success} t_z} \\
        0 & 0 & 0 & 1
    \end{pmatrix}
\boldsymbol{A} = \begin{pmatrix} {\color{m-info} s_x} & 0 & 0 & {\color{m-success} t_x} \\ 0 & {\color{m-info} s_y} & 0 & {\color{m-success} t_y} \\ 0 & 0 & {\color{m-info} s_z} & {\color{m-success} t_z} \\ 0 & 0 & 0 & 1 \end{pmatrix}

The M_MATH_CACHE_FILE set­ting (de­fault­ing to m.math.cache in the site root di­rec­to­ry) de­scribes a file used for caching ren­dered La­TeX math for­mu­las for speed­ing up sub­se­quent runs. Cached out­put that’s no longer need­ed is pe­ri­od­i­cal­ly pruned and new for­mu­las added to the file. Set it to None to dis­able caching.

Code

Down­load the m/code.py and an­silex­er.py files, put them in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.code pack­age to your PLUGINS in pelicanconf.py. This plug­in as­sumes pres­ence of m.html­san­i­ty.

PLUGINS += ['m-htmlsanity', 'm.code']

In ad­di­tion you need to have Pyg­ments in­stalled. Get it via pip or your dis­tri­bu­tion pack­age man­ag­er:

pip3 install Pygments

The plug­in over­rides the builtin do­cu­tils code di­rec­tive and code in­ter­pret­ed text role, re­places Pel­i­can code-block di­rec­tive and:

  • Wraps Pyg­ments out­put in <code> el­e­ment for in­line code and <pre> el­e­ment for code blocks with .m-code CSS class ap­plied.
  • Re­moves use­less CSS class­es from the out­put.

Put code blocks in­to the .. code:: di­rec­tive and spec­i­fy the lan­guage via a pa­ram­e­ter. Use :hl_lines: op­tion to high­light lines; if you want to add ad­di­tion­al CSS class­es, use the :class: op­tion.

.. code:: c++
    :hl_lines: 4 5
    :class: m-inverted

    #include <iostream>

    int main() {
        std::cout << "Hello world!" << std::endl;
        return 0;
    }
#include <iostream>

int main() {
    std::cout << "Hello world!" << std::endl;
    return 0;
}

The builtin in­clude di­rec­tive is al­so patched to use the im­proved code di­rec­tive. Sim­ply spec­i­fy ex­ter­nal code snip­pets file­name and set the lan­guage us­ing the :code: op­tion. All op­tions of the .. code:: di­rec­tive are sup­port­ed as well.

.. include:: snippet.cpp
    :code: c++
    :start-line: 2
int main() {
    std::cout << "Hello world!" << std::endl;
    return 0;
}

For in­line code high­light­ing, use :code: in­ter­pret­ed text role. To spec­i­fy which lan­guage should be high­light­ed, de­rive a cus­tom role from it:

.. role:: cmake(code)
    :language: cmake

.. role:: cpp(code)
    :language: cpp

With the :cmake:`add_executable(foo bar.cpp)` CMake command you can create an
executable from a file that contains just :cpp:`int main() { return 666; }` and
nothing else.

With the add_executable(foo bar.cpp) CMake com­mand you can cre­ate an ex­e­cutable from a file that con­tains just int main() { return 666; } and noth­ing else.

Col­ored ter­mi­nal out­put

Use the ansi pseu­do-lan­guage for high­light­ing col­ored ter­mi­nal out­put. The plug­in will take care of the rest like us­ing the cus­tom Pyg­ments lex­er and as­sign­ing a prop­er CSS class. Be­cause AN­SI es­cape codes might cause prob­lems with some ed­i­tors and look con­fus­ing when viewed via git diff on the ter­mi­nal, it’s best to have the list­ings in ex­ter­nal files and use .. include:::

.. include:: console.ansi
    :code: ansi
![mosra@don-perverzo m.css]$ ls
CONTRIBUTING.rst  CREDITS.rst  doc      pelican-plugins  README.rst
COPYING           css          doxygen  pelican-theme    site