| Name | pelican-render-math JSON |
| Version |
1.0.4
JSON |
| download |
| home_page | None |
| Summary | Render mathematics in Pelican site content |
| upload_time | 2024-11-02 11:48:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | ~=3.9 |
| license | AGPL-3.0 |
| keywords |
pelican
plugin
math
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Render Math Plugin for Pelican
==============================
[](https://github.com/pelican-plugins/render-math/actions)
[](https://pypi.org/project/pelican-render-math/)
[](https://pypi.org/project/pelican-render-math/)
This plugin gives [Pelican][] the ability to render mathematics inside post
content. It accomplishes this by using the [MathJax][] JavaScript engine.
The plugin also makes [Typogrify][] and recognized math play nicely together by
ensuring [Typogrify][] does not alter math content.
Both Markdown and reStructuredText are supported.
Requirements
------------
* [Pelican][] version *4.5* or above is required.
* [Typogrify][] version *2.0.7* or higher is needed for Typogrify to behave
properly with this plugin. If this version is not available, Typogrify will be
disabled for the entire site.
* [BeautifulSoup][] 4+ is required to correct summaries. If BeautifulSoup is not
installed, summary processing will be ignored, even if specified in user
settings.
Installation
------------
This plugin can be installed via:
python -m pip install pelican-render-math
As long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `render_math` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.
Once the plugin has been installed according to those instructions, your site
should be capable of rendering math using the MathJax JavaScript engine.
No alterations to the template are 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 have control over the template
and want to insert the script manually.
### Typogrify
In the past, using [Typogrify][] would alter math content, 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 or higher. If this version is not present, the
plugin will disable Typogrify for the entire site.
### BeautifulSoup
Pelican creates summaries by truncating the post content 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, [BeautifulSoup][] is used. If it is not installed, no summary
processing will happen.
Usage
-----
### Templates
No template alteration is needed 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](https://docs.mathjax.org/en/latest/input/tex/extensions.html)
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 [BeautifulSoup][] 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 display math aligned to the left:
MATH_JAX = {'color':'blue','align':left}
Use the [color](https://docs.mathjax.org/en/latest/input/tex/extensions/color.html)
and [mhchem](https://docs.mathjax.org/en/latest/input/tex/extensions/mhchem.html)
extensions:
MATH_JAX = {'tex_extensions': ['color.js','mhchem.js']}
#### Resulting HTML
Inline 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.
### Inline 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 content, the plugin will
automatically set the
[math_output](https://docutils.sourceforge.io/docs/user/config.html#math-output)
configuration setting to `mathjax`.
### Inline Math
Inline math needs to use the [math
role](https://docutils.sourceforge.io/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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#math):
```rst
.. math::
α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
```
Enabling Additional Features
----------------------------
In order for `\frac`, equation numbering, and other features to work, the MathJAX JavaScript file must be added to the HTML file, either via your theme's template configuration (if supported) or by editing the relevant template file directly. The current MathJAX CDN is hosted at `http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML`, and the code to add it to the HTML is provided below.
```html
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
```
As long as this script is loaded in either the head or body of the HTML output, the complex expressions are also converted.
Contributing
------------
Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].
To start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.
[BeautifulSoup]: https://www.crummy.com/software/BeautifulSoup/
[MathJax]: https://www.mathjax.org/
[Pelican]: https://github.com/getpelican/pelican
[Typogrify]: https://github.com/mintchaos/typogrify
[existing issues]: https://github.com/pelican-plugins/render-math/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
License
-------
This project is licensed under the AGPL-3.0 license.
Raw data
{
"_id": null,
"home_page": null,
"name": "pelican-render-math",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.9",
"maintainer_email": null,
"keywords": "pelican, plugin, math",
"author": null,
"author_email": "Pelican Dev Team <authors@getpelican.com>",
"download_url": "https://files.pythonhosted.org/packages/ae/57/1643cb246c719152c0f3382e392d01c56c16de8929be6a8b1c3ee48921b4/pelican_render_math-1.0.4.tar.gz",
"platform": null,
"description": "Render Math Plugin for Pelican\n==============================\n\n[](https://github.com/pelican-plugins/render-math/actions)\n[](https://pypi.org/project/pelican-render-math/)\n[](https://pypi.org/project/pelican-render-math/)\n\n\nThis plugin gives [Pelican][] the ability to render mathematics inside post\ncontent. It accomplishes this by using the [MathJax][] JavaScript engine.\n\nThe plugin also makes [Typogrify][] and recognized math play nicely together by\nensuring [Typogrify][] does not alter math content.\n\nBoth Markdown and reStructuredText are supported.\n\nRequirements\n------------\n\n* [Pelican][] version *4.5* or above is required.\n* [Typogrify][] version *2.0.7* or higher is needed for Typogrify to behave\n properly with this plugin. If this version is not available, Typogrify will be\n disabled for the entire site.\n* [BeautifulSoup][] 4+ is required to correct summaries. If BeautifulSoup is not\n installed, summary processing will be ignored, even if specified in user\n settings.\n\nInstallation\n------------\n\nThis plugin can be installed via:\n\n python -m pip install pelican-render-math\n\nAs long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `render_math` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.\n\nOnce the plugin has been installed according to those instructions, your site\nshould be capable of rendering math using the MathJax JavaScript engine.\nNo alterations to the template are needed \u2014 just use and enjoy!\n\nHowever, if you wish, you can set the `auto_insert` setting to `False` which\nwill disable the MathJax script from being automatically inserted into the\ncontent. You would only want to do this if you have control over the template\nand want to insert the script manually.\n\n### Typogrify\n\nIn the past, using [Typogrify][] would alter math content, resulting in math\nthat could not be rendered by [MathJax][]. The only option was to ensure that\n[Typogrify][] was disabled in the settings.\n\nThe problem has been rectified in this plugin, but it requires at a minimum\n[Typogrify][] version 2.0.7 or higher. If this version is not present, the\nplugin will disable Typogrify for the entire site.\n\n### BeautifulSoup\n\nPelican creates summaries by truncating the post content to a specified user\nlength. The truncation process is oblivious to any math and can therefore\ndestroy the math output in the summary.\n\nTo restore math, [BeautifulSoup][] is used. If it is not installed, no summary\nprocessing will happen.\n\nUsage\n-----\n\n### Templates\n\nNo template alteration is needed for this plugin to work. Just install the\nplugin and start writing your math.\n\n### Settings\n\nCertain MathJax rendering options can be set. These options are in a dictionary\nvariable called `MATH_JAX` in the Pelican settings file.\n\nThe dictionary can be set with the following keys:\n\n * `align`: [string] controls how displayed math will be aligned. Can be set to\n either `'left'`, `'right'` or `'center'`. **Default Value**: `'center'`.\n * `auto_insert`: [boolean] will insert the MathJax script into content that it\n is detected to have math in it. Setting it to false is not recommended.\n **Default Value**: `True`\n * `indent`: [string] if `align` not set to `'center'`, then this controls the\n indent level. **Default Value**: `'0em'`.\n * `show_menu`: [boolean] controls whether the MathJax contextual menu is\n shown. **Default Value**: `True`\n * `process_escapes`: [boolean] controls whether MathJax processes escape\n sequences. **Default Value**: `True`\n * `MathJax_font`: [string] will force MathJax to use the chosen font. Current\n choices for the font is `sanserif`, `typewriter` or `fraktur`. If this is\n not set, it will use the default font settings. **Default Value**: `default`\n * `latex_preview`: [string] controls the preview message users are shown while\n MathJax is rendering LaTex. If set to `'Tex'`, then the TeX code is used as\n the preview (which will be visible until it is processed by MathJax).\n **Default Value**: `'Tex'`\n * `color`: [string] controls the color of the MathJax rendered font. **Default\n Value**: `'inherit'`\n * `linebreak_automatic`: [boolean] If set, MathJax will try to *intelligently*\n break up displayed math (Note: It will not work for inline math). This is\n very useful for a responsive site. It is turned off by default due to it\n potentially being CPU expensive. **Default Value**: `False`\n * `tex_extensions`: [list] a list of [latex\n extensions](https://docs.mathjax.org/en/latest/input/tex/extensions.html)\n accepted by MathJax. **Default Value**: `[]` (empty list)\n * `responsive`: [boolean] tries to make displayed math render responsively. It\n does by determining if the width is less than `responsive_break` (see below)\n and if so, sets `align` to `left`, `indent` to `0em` and\n `linebreak_automatic` to `True`. **Default Value**: `False` (defaults to\n `False` for backward compatibility)\n * `responsive_break`: [integer] a number (in pixels) representing the width\n breakpoint that is used when setting `responsive_align` to `True`. **Default\n Value**: 768\n * `process_summary`: [boolean] ensures math will render in summaries and fixes\n math in that were cut off. Requires [BeautifulSoup][] be installed. **Default\n Value**: `True`\n * `message_style`: [string] This value controls the verbosity of the messages\n in the lower left-hand corner. Set it to `None` to eliminate all messages.\n **Default Value**: normal\n\n#### Settings Examples\n\nMake math render in blue and display math aligned to the left:\n\n MATH_JAX = {'color':'blue','align':left}\n\nUse the [color](https://docs.mathjax.org/en/latest/input/tex/extensions/color.html)\nand [mhchem](https://docs.mathjax.org/en/latest/input/tex/extensions/mhchem.html)\nextensions:\n\n MATH_JAX = {'tex_extensions': ['color.js','mhchem.js']}\n\n#### Resulting HTML\n\nInline math is wrapped in `span` tags, while displayed math is wrapped in\n`div` tags. These tags will have a class attribute that is set to `math` which\ncan be used by template designers to alter the display of the math.\n\nMarkdown\n--------\n\nThis plugin implements a custom extension for Markdown resulting in math being\na \"first class citizen\" for Pelican.\n\n### Inline Math\n\nMath between `$`..`$`, for example, `$`x^2`$`, will be rendered inline with\nrespect to the current HTML block. Note: To use inline math, there must *not*\nbe any whitespace before the ending `$`. So for example:\n\n * **Relevant inline math**: `$e=mc^2$`\n * **Will not render as inline math**: `$40 vs $50`\n\n### Displayed Math\n\nMath between `$$`..`$$` will be rendered \"block style\", for example,\n`$$`x^2`$$`, will be rendered centered in a new paragraph.\n\n#### Other Latex Display Math Commands\n\nThe other LaTeX commands which usually invoke display math mode from text mode\nare supported, and are automatically treated like `$$`-style displayed math in\nthat they are rendered \"block\" style on their own lines. For example,\n`\\begin{equation}` x^2 `\\end{equation}`, will be rendered in its own block with\na right justified equation number at the top of the block. This equation number\ncan be referenced in the document. To do this, use a `label` inside of the\nequation format and then refer to that label using `ref`. For example:\n`\\begin{equation}` `\\label{eq}` X^2 `\\end{equation}`. Now refer to that\nequation number by `$`\\ref{eq}`$`.\n\nreStructuredText\n----------------\n\nIf there is math detected in reStructuredText content, the plugin will\nautomatically set the\n[math_output](https://docutils.sourceforge.io/docs/user/config.html#math-output)\nconfiguration setting to `mathjax`.\n\n### Inline Math\n\nInline math needs to use the [math\nrole](https://docutils.sourceforge.io/docs/ref/rst/roles.html#math):\n\n```\nThe area of a circle is :math:`A_\\text{c} = (\\pi/4) d^2`.\n```\n\n### Displayed Math\n\nDisplayed math uses the [math block](https://docutils.sourceforge.io/docs/ref/rst/directives.html#math):\n\n```rst\n.. math::\n\n \u03b1_t(i) = P(O_1, O_2, \u2026 O_t, q_t = S_i \u03bb)\n```\n\nEnabling Additional Features\n----------------------------\n\nIn order for `\\frac`, equation numbering, and other features to work, the MathJAX JavaScript file must be added to the HTML file, either via your theme's template configuration (if supported) or by editing the relevant template file directly. The current MathJAX CDN is hosted at `http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML`, and the code to add it to the HTML is provided below.\n\n```html\n<script type=\"text/javascript\" src=\"http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML\"></script>\n```\nAs long as this script is loaded in either the head or body of the HTML output, the complex expressions are also converted.\n\nContributing\n------------\n\nContributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].\n\nTo start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.\n\n\n[BeautifulSoup]: https://www.crummy.com/software/BeautifulSoup/\n[MathJax]: https://www.mathjax.org/\n[Pelican]: https://github.com/getpelican/pelican\n[Typogrify]: https://github.com/mintchaos/typogrify\n[existing issues]: https://github.com/pelican-plugins/render-math/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\nLicense\n-------\n\nThis project is licensed under the AGPL-3.0 license.\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Render mathematics in Pelican site content",
"version": "1.0.4",
"project_urls": {
"Funding": "https://donate.getpelican.com/",
"Homepage": "https://github.com/pelican-plugins/render-math",
"Issue Tracker": "https://github.com/pelican-plugins/render-math/issues"
},
"split_keywords": [
"pelican",
" plugin",
" math"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f8fdd7acf929679d0a477a7f065445b2ebac636bfc9018673b91ef4ef3634b62",
"md5": "5388120b4039c0aeb9e44f6441516818",
"sha256": "a03b910790523c9160e14e02e920d5cab6864120df0d60708e95ff09d5a49e77"
},
"downloads": -1,
"filename": "pelican_render_math-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5388120b4039c0aeb9e44f6441516818",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.9",
"size": 28828,
"upload_time": "2024-11-02T11:48:34",
"upload_time_iso_8601": "2024-11-02T11:48:34.701145Z",
"url": "https://files.pythonhosted.org/packages/f8/fd/d7acf929679d0a477a7f065445b2ebac636bfc9018673b91ef4ef3634b62/pelican_render_math-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ae571643cb246c719152c0f3382e392d01c56c16de8929be6a8b1c3ee48921b4",
"md5": "5f4f010ace7fba37470738e2ab894153",
"sha256": "6a8f331bdb875a80a8349b59f5bc8e5749ee3d3802e6f2c3164eee7f90253a29"
},
"downloads": -1,
"filename": "pelican_render_math-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "5f4f010ace7fba37470738e2ab894153",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.9",
"size": 30138,
"upload_time": "2024-11-02T11:48:35",
"upload_time_iso_8601": "2024-11-02T11:48:35.976361Z",
"url": "https://files.pythonhosted.org/packages/ae/57/1643cb246c719152c0f3382e392d01c56c16de8929be6a8b1c3ee48921b4/pelican_render_math-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-02 11:48:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pelican-plugins",
"github_project": "render-math",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pelican-render-math"
}
