# math-svg: A Plugin for Pelican
[](https://github.com/f-koehler/pelican-math-svg/actions)
[](https://pypi.org/project/pelican-math-svg/)
[](https://results.pre-commit.ci/latest/github/f-koehler/pelican-math-svg/main)
Render math expressions to svg and embed them.
## Installation
This plugin can be installed via:
```shell
python -m pip install pelican-math-svg
```
Afterwards, add the plugin to the `PLUGINS` list in your `pelicanconf.py` file, e.g.:
```python
PLUGINS = [
"math_svg",
]
```
## Multi-Core Rendering
To use multi-core rendering of equations (highly recommended, especially when many equations have to be rendered) change the `html` target in the `Makefile` of your pelican site to a three step process:
```makefile
html:
PELICAN_MATH_SVG_DRY=True "$(PELICAN)" "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS)
pelican-math-svg render -j $(shell nproc)
"$(PELICAN)" "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS)
```
The first commands will execute `math-svg` in dry-mode and only populate the equation database without actually rendering anything.
The second command will render all missing equations in parallel.
The number of threads is specified by the `-j` flag, in this example all CPU cores are used.
Replace `$(shell nproc)` with a number to use a fixed number of cores.
The last command is the usual pelican command and produces the output files again, know including the rendered equations.
## Requirements
- required LaTeX tools (all included in TeX Live and possibly other LaTeX distributions):
- `lualatex` (or another LaTeX compiler if changed in the settings, [see below](#configuration))
- `pdfcrop`
- `dvisvgm`
- `scour` (optional)
- `svgo` (optional)
## Usage
In Markdown you can use `$x$` for inline math and
```
$$
\int x^2
$$
```
for display math.
It is required to set the stroke color using the `strokeonly` class (this class name can be changed, see [configuration options below](#configuration)), otherwise lines would be rendered white:
```css
svg path.strokeonly {
color: #000;
}
```
To change the fill color for equations as well, thus essential changing the default color for math, specify the following additionally:
```css
span.math svg path,
div.math svg path {
fill: #000;
}
```
## Configuration
In your `pelicanconf.py` you can use the following options to tweak the behavior of the plugin:
| Setting | Description | Default Value |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MATH_SVG["titles"] | Whether to generate `<title>` tags containing the raw LaTeX code (recommended for accessibility). | `True` |
| `MATH_SVG["scale_inline"]` | scaling factor for inline math | `1.0` |
| `MATH_SVG["scale_display"]` | scaling factor for display math | `1.0` |
| `MATH_SVG["strokeonly_class]` | CSS class for SVG paths that have no filling and a black stroke color, useful when changing the color of rendered equations | `strokeonly` |
| `MATH_SVG["latex"]["args"]` | CLI arguments of the invoked LaTeX compiler | `"--interaction=errorstopmode", "--halt-on-error"` |
| `MATH_SVG["latex"]["preamble"]` | preamble of the generated LaTeX document | `[r"\documentclass[preview,border={2pt 0pt}]{standalone}",r"\usepackage{amsmath}",r"\usepackage{amssymb}",]` |
| `MATH_SVG["latex"]["program"]` | LaTeX compiler to use | `lualatex` |
| `MATH_SVG["pdfcrop"]["args"]` | CLI arguments for `pdfcrop` | `--hires` |
| `MATH_SVG["dvisvgm"]["args"]` | CLI arguments for `dvisvgm` | `["--pdf", "--optimize=all", "--no-fonts", "--exact-bbox"]` |
| `MATH_SVG["scour"]["args"]` | CLI arguments for `scour` | `["--strip-xml-prolog", "--remove-descriptions", "--remove-metadata", "--enable-comment-stripping", "--strip-xml-space", "--enable-id-stripping",]` |
| `MATH_SVG["scour"]["enabled"]` | whether to use `scour` to optimize SVG output | `True` if `scour` is in `$PATH`, `False` otherwise |
| `MATH_SVG["svgo"]["args"]` | CLI arguments for `svgo` | `["--multipass", "--precision", "5"]` |
| `MATH_SVG["svgo"]["enabled"]` | whether to use `svgo` to optimize SVG output | `True` if `svgo` is in `$PATH`, `False` otherwise |
## 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.
[existing issues]: https://github.com/f-koehler/pelican-math-svg/issues
[contributing to pelican]: https://docs.getpelican.com/en/latest/contribute.html
## License
This project is licensed under the GPLv3 license.
Raw data
{
"_id": null,
"home_page": "https://github.com/f-koehler/pelican-math-svg",
"name": "pelican-math-svg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "pelican,plugin",
"author": "Fabian K\u00f6hler",
"author_email": "fabian.koehler@protonmail.ch",
"download_url": "https://files.pythonhosted.org/packages/8b/26/03b1603e9799bc8540dac33293c764dcfaa2c085f35fc24c5bf2ee9c94fc/pelican_math_svg-0.10.5.tar.gz",
"platform": null,
"description": "# math-svg: A Plugin for Pelican\n\n[](https://github.com/f-koehler/pelican-math-svg/actions)\n[](https://pypi.org/project/pelican-math-svg/)\n\n[](https://results.pre-commit.ci/latest/github/f-koehler/pelican-math-svg/main)\n\nRender math expressions to svg and embed them.\n\n## Installation\n\nThis plugin can be installed via:\n\n```shell\npython -m pip install pelican-math-svg\n```\n\nAfterwards, add the plugin to the `PLUGINS` list in your `pelicanconf.py` file, e.g.:\n\n```python\nPLUGINS = [\n \"math_svg\",\n]\n```\n\n## Multi-Core Rendering\n\nTo use multi-core rendering of equations (highly recommended, especially when many equations have to be rendered) change the `html` target in the `Makefile` of your pelican site to a three step process:\n\n```makefile\nhtml:\n PELICAN_MATH_SVG_DRY=True \"$(PELICAN)\" \"$(INPUTDIR)\" -o \"$(OUTPUTDIR)\" -s \"$(CONFFILE)\" $(PELICANOPTS)\n pelican-math-svg render -j $(shell nproc)\n \"$(PELICAN)\" \"$(INPUTDIR)\" -o \"$(OUTPUTDIR)\" -s \"$(CONFFILE)\" $(PELICANOPTS)\n```\n\nThe first commands will execute `math-svg` in dry-mode and only populate the equation database without actually rendering anything.\nThe second command will render all missing equations in parallel.\nThe number of threads is specified by the `-j` flag, in this example all CPU cores are used.\nReplace `$(shell nproc)` with a number to use a fixed number of cores.\nThe last command is the usual pelican command and produces the output files again, know including the rendered equations.\n\n## Requirements\n\n- required LaTeX tools (all included in TeX Live and possibly other LaTeX distributions):\n - `lualatex` (or another LaTeX compiler if changed in the settings, [see below](#configuration))\n - `pdfcrop`\n - `dvisvgm`\n- `scour` (optional)\n- `svgo` (optional)\n\n## Usage\n\nIn Markdown you can use `$x$` for inline math and\n\n```\n$$\n \\int x^2\n$$\n```\n\nfor display math.\n\nIt is required to set the stroke color using the `strokeonly` class (this class name can be changed, see [configuration options below](#configuration)), otherwise lines would be rendered white:\n\n```css\nsvg path.strokeonly {\n color: #000;\n}\n```\n\nTo change the fill color for equations as well, thus essential changing the default color for math, specify the following additionally:\n\n```css\nspan.math svg path,\ndiv.math svg path {\n fill: #000;\n}\n```\n\n## Configuration\n\nIn your `pelicanconf.py` you can use the following options to tweak the behavior of the plugin:\n\n| Setting | Description | Default Value |\n| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `MATH_SVG[\"titles\"] | Whether to generate `<title>` tags containing the raw LaTeX code (recommended for accessibility). | `True` |\n| `MATH_SVG[\"scale_inline\"]` | scaling factor for inline math | `1.0` |\n| `MATH_SVG[\"scale_display\"]` | scaling factor for display math | `1.0` |\n| `MATH_SVG[\"strokeonly_class]` | CSS class for SVG paths that have no filling and a black stroke color, useful when changing the color of rendered equations | `strokeonly` |\n| `MATH_SVG[\"latex\"][\"args\"]` | CLI arguments of the invoked LaTeX compiler | `\"--interaction=errorstopmode\", \"--halt-on-error\"` |\n| `MATH_SVG[\"latex\"][\"preamble\"]` | preamble of the generated LaTeX document | `[r\"\\documentclass[preview,border={2pt 0pt}]{standalone}\",r\"\\usepackage{amsmath}\",r\"\\usepackage{amssymb}\",]` |\n| `MATH_SVG[\"latex\"][\"program\"]` | LaTeX compiler to use | `lualatex` |\n| `MATH_SVG[\"pdfcrop\"][\"args\"]` | CLI arguments for `pdfcrop` | `--hires` |\n| `MATH_SVG[\"dvisvgm\"][\"args\"]` | CLI arguments for `dvisvgm` | `[\"--pdf\", \"--optimize=all\", \"--no-fonts\", \"--exact-bbox\"]` |\n| `MATH_SVG[\"scour\"][\"args\"]` | CLI arguments for `scour` | `[\"--strip-xml-prolog\", \"--remove-descriptions\", \"--remove-metadata\", \"--enable-comment-stripping\", \"--strip-xml-space\", \"--enable-id-stripping\",]` |\n| `MATH_SVG[\"scour\"][\"enabled\"]` | whether to use `scour` to optimize SVG output | `True` if `scour` is in `$PATH`, `False` otherwise |\n| `MATH_SVG[\"svgo\"][\"args\"]` | CLI arguments for `svgo` | `[\"--multipass\", \"--precision\", \"5\"]` |\n| `MATH_SVG[\"svgo\"][\"enabled\"]` | whether to use `svgo` to optimize SVG output | `True` if `svgo` is in `$PATH`, `False` otherwise |\n\n## Contributing\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[existing issues]: https://github.com/f-koehler/pelican-math-svg/issues\n[contributing to pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\n## License\n\nThis project is licensed under the GPLv3 license.\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Render math expressions to svg and embed them.",
"version": "0.10.5",
"project_urls": {
"Documentation": "https://docs.getpelican.com",
"Funding": "https://donate.getpelican.com/",
"Homepage": "https://github.com/f-koehler/pelican-math-svg",
"Issue Tracker": "https://github.com/f-koehler/pelican-math-svg/issues",
"Repository": "https://github.com/f-koehler/pelican-math-svg"
},
"split_keywords": [
"pelican",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "780b231d201ece4d7c7c5c53ceb0815b3508e6800405e118dc70705938c06037",
"md5": "ff28c32e84eee858a7641e5b0f0c0b20",
"sha256": "4b9e9e588e7d8f8fc3117e678e7f3e35ff3642af146da7aef87dd4abe2a3c0b0"
},
"downloads": -1,
"filename": "pelican_math_svg-0.10.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff28c32e84eee858a7641e5b0f0c0b20",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 22962,
"upload_time": "2023-06-27T10:56:52",
"upload_time_iso_8601": "2023-06-27T10:56:52.421233Z",
"url": "https://files.pythonhosted.org/packages/78/0b/231d201ece4d7c7c5c53ceb0815b3508e6800405e118dc70705938c06037/pelican_math_svg-0.10.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b2603b1603e9799bc8540dac33293c764dcfaa2c085f35fc24c5bf2ee9c94fc",
"md5": "6a42271e3adee632c3c20ab464086f2d",
"sha256": "16c5aa7931d91552ae5b80fc36f77f435998824b1990c5c7a02b7c3667970133"
},
"downloads": -1,
"filename": "pelican_math_svg-0.10.5.tar.gz",
"has_sig": false,
"md5_digest": "6a42271e3adee632c3c20ab464086f2d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 22172,
"upload_time": "2023-06-27T10:56:53",
"upload_time_iso_8601": "2023-06-27T10:56:53.892091Z",
"url": "https://files.pythonhosted.org/packages/8b/26/03b1603e9799bc8540dac33293c764dcfaa2c085f35fc24c5bf2ee9c94fc/pelican_math_svg-0.10.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-27 10:56:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "f-koehler",
"github_project": "pelican-math-svg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pelican-math-svg"
}
JSON
