forked from varia/varia.website
165 lines
7.6 KiB
Markdown
165 lines
7.6 KiB
Markdown
Math Render Plugin For Pelican
|
||
==============================
|
||
This plugin gives pelican the ability to render mathematics. It accomplishes
|
||
this by using the [MathJax](http://www.mathjax.org/) javascript engine.
|
||
|
||
The plugin also ensures that Typogrify and recognized math "play" nicely together, by
|
||
ensuring [Typogrify](https://github.com/mintchaos/typogrify) does not alter math content.
|
||
|
||
Both Markdown and reStructuredText is supported.
|
||
|
||
Requirements
|
||
------------
|
||
|
||
* Pelican version *3.6* or above is required.
|
||
* Typogrify version *2.0.7* or higher is needed for Typogrify to play
|
||
"nicely" with this plugin. If this version is not available, Typogrify
|
||
will be disabled for the entire site.
|
||
* BeautifulSoup4 is required to correct summaries. If BeautifulSoup4 is
|
||
not installed, summary processing will be ignored, even if specified
|
||
in user settings.
|
||
|
||
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](https://github.com/mintchaos/typogrify) 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](https://pypi.python.org/pypi/typogrify) (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](https://pypi.python.org/pypi/beautifulsoup4/4.4.0)
|
||
is used. If it is not installed, no summary processing will happen.
|
||
|
||
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:
|
||
|
||
* `align`: [string] controls how displayed math will be aligned. Can be set to either
|
||
`'left'`, `'right'` or `'center'`. **Default Value**: `'center'`.
|
||
* `auto_insert`: [boolean] will insert the mathjax script into content that it is
|
||
detected to have math in it. Setting it to false is not recommended.
|
||
**Default Value**: `True`
|
||
* `indent`: [string] if `align` not set to `'center'`, then this controls the indent
|
||
level. **Default Value**: `'0em'`.
|
||
* `show_menu`: [boolean] controls whether the mathjax contextual menu is shown.
|
||
**Default Value**: `True`
|
||
* `process_escapes`: [boolean] controls whether mathjax processes escape sequences.
|
||
**Default Value**: `True`
|
||
* `mathjax_font`: [string] will force mathjax to use the chosen font. Current choices
|
||
for the font is `sanserif`, `typewriter` or `fraktur`. If this is not set, it will
|
||
use the default font settings. **Default Value**: `default`
|
||
* `latex_preview`: [string] controls the preview message users are shown 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`: [string] controls the color of the mathjax rendered font. **Default Value**: `'inherit'`
|
||
* `linebreak_automatic`: [boolean] If set, Mathjax will try to *intelligently* break up displayed math
|
||
(Note: It will not work for inline math). This is very useful for a responsive site. It
|
||
is turned off by default due to it potentially being CPU expensive. **Default Value**: `False`
|
||
* `tex_extensions`: [list] a list of [latex extensions](http://docs.mathjax.org/en/latest/tex.html#tex-and-latex-extensions)
|
||
accepted by mathjax. **Default Value**: `[]` (empty list)
|
||
* `responsive`: [boolean] tries to make displayed math render responsively. It does by determining if the width
|
||
is less than `responsive_break` (see below) and if so, sets `align` to `left`, `indent` to `0em` and `linebreak_automatic` to `True`.
|
||
**Default Value**: `False` (defaults to `False` for backward compatibility)
|
||
* `responsive_break`: [integer] a number (in pixels) representing the width breakpoint that is used
|
||
when setting `responsive_align` to `True`. **Default Value**: 768
|
||
* `process_summary`: [boolean] ensures math will render in summaries and fixes math in that were cut off.
|
||
Requires [BeautifulSoup4](http://www.crummy.com/software/BeautifulSoup/bs4/doc/) be installed. **Default Value**: `True`
|
||
* `message_style`: [string] This value controls the verbosity of the messages in the lower left-hand corner. Set it to `None` to eliminate all messages.
|
||
**Default Value**: normal
|
||
|
||
#### Settings Examples
|
||
Make math render in blue and displaymath align to the left:
|
||
|
||
MATH_JAX = {'color':'blue','align':left}
|
||
|
||
Use the [color](http://docs.mathjax.org/en/latest/tex.html#color) and
|
||
[mhchem](http://docs.mathjax.org/en/latest/tex.html#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:
|
||
|
||
* **Relevant inline math**: `$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}`$`.
|
||
|
||
reStructuredText
|
||
----------------
|
||
If there is math detected in reStructuredText document, the plugin will automatically
|
||
set the [math_output](http://docutils.sourceforge.net/docs/user/config.html#math-output) configuration setting to `MathJax`.
|
||
|
||
###Inlined Math
|
||
Inlined math needs to use the [math role](http://docutils.sourceforge.net/docs/ref/rst/roles.html#math):
|
||
|
||
```
|
||
The area of a circle is :math:`A_\text{c} = (\pi/4) d^2`.
|
||
```
|
||
|
||
###Displayed Math
|
||
Displayed math uses the [math block](http://docutils.sourceforge.net/docs/ref/rst/directives.html#math):
|
||
|
||
```
|
||
.. math::
|
||
|
||
α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
|
||
```
|