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']

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-get 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.
  • Adds a <title> and <desc> 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}
LaTeX Math \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 LaTeX Math \hat q^* = q_0^* + q_\epsilon^* , while du­al-con­ju­ga­tion gives LaTeX Math \overline{\hat q} = q_0 - \epsilon q_\epsilon .

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