| Name | pelican-graphviz JSON |
| Version |
1.2.5
JSON |
| download |
| home_page | None |
| Summary | Pelican plugin supporting Graphviz images in articles |
| upload_time | 2024-04-14 11:29:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4.0,>=3.8.1 |
| license | AGPL-3.0 |
| keywords |
pelican
plugin
graphviz
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Graphviz: A Plugin for Pelican
==============================
[](https://github.com/pelican-plugins/graphviz/actions)
[](https://pypi.org/project/pelican-graphviz/)
Graphviz is a Pelican plugin that allows the inclusion of [Graphviz][] images using the Markdown markup format. The code for the Graphviz figure is included as a block in the article’s source, and the image is embedded in HTML using the Base64 format.
[Graphviz]: https://www.graphviz.org
Installation
------------
This plugin can be installed via:
python -m pip install pelican-graphviz
Graphviz must be installed on the system, otherwise this plugin will be deactivated. Graphviz can be installed on Debian-based systems via:
sudo aptitude install graphviz
For macOS, Graphviz can be installed via Homebrew:
brew install graphviz
Usage
-----
In the Markdown source, the Graphviz code must be inserted as an individual block (i.e., separated from the rest of the material by blank lines), like the following:
```markdwon
..graphviz dot
digraph G {
graph [rankdir = LR];
Hello -> World
}
```
This will insert an image in your article like this:
The block must start with `..graphviz` (this is configurable — see below). The word `dot` in the first line indicates the program that will be run to produce the image. The available programs are: `dot`, `neato`, `twopi`, `circo`, `fdp`, `sfdp`, and `patchwork` (see the [Graphviz documentation][] for details). The Graphviz code must start in the second line of the block. Notice that *newlines are not allowed inside the Graphviz block*.
[Graphviz documentation]: https://www.graphviz.org/documentation/
Styling with CSS
----------------
The image is generated in HTML with an `<img>` element inside an HTML element (by default a `<div>`, but this is configurable — see below). The latter has class `graphviz` (this is also configurable — see below). A possible CSS styling would be:
```css
div.graphviz {
margin: 10px;
}
div.graphviz img {
display: block;
padding: 5px;
margin-left: auto;
margin-right: auto;
text-align: center;
border-style: solid;
border-width: 1px;
border-color: rgb(192, 177, 177);
-webkit-border-radius: 5px;
}
```
Configuration
-------------
The following variables can be set in the Pelican settings file:
- `GRAPHVIZ_HTML_ELEMENT`: The HTML inside which the generated Graphviz image is inserted (defaults to `'div'`; another sensible possibility would be `'span'`).
- `GRAPHVIZ_IMAGE_CLASS`: Class of the `<div>` element including the generated Graphviz image (defaults to `'graphviz'`).
- `GRAPHVIZ_BLOCK_START`: Starting tag for the Graphviz block in Markdown (defaults to `'..graphviz'`).
- `GRAPHVIZ_COMPRESS`: Compress the resulting SVG XML to an image (defaults to `True`). Without compression, more SVG features are available, for instance including clickable URLs inside the Graphviz diagram.
The values above can be overridden for each individual block using the syntax below:
```markdwon
..graphviz [key=val, ...] dot
```
The allowed keys are `html-element`, `image-class`, and `compress`. For the latter, the value can be either `yes` or `no`.
Output Image Format
-------------------
The format of the embedded image is SVG, and there is currently no way to change it. This format was chosen over others (like PNG) for two reasons. First, the generated SRC string in Base64 seem to be shorter for SVG than for PNG. Second, the image will be available in the browser in a high-quality vectorized format. As a caveat, notice that this choice may prevent display in browsers lacking proper SVG support.
Alternatives
------------
An alternative to this plugin is the [Graphviz tag][] provided by the [Liquid Tags plugin][], which differs from this plugin in several respects. First, the Liquid Tags version uses the syntax `{% graphviz { <program> […] } %}`, while this Graphviz plugin uses the Markdown extension syntax `..graphviz <program> […]`. Regarding the rendered output, the differences are:
- Both plugins output an element with `class="graphviz"`. However, only the Graphviz plugin allows you to change the class name via a configuration variable (`GRAPHVIZ_IMAGE_CLASS`).
- Liquid Tags encodes the image as `src="data:image/png;base64,[…]"`, while the Graphviz plugin encodes it as `src="data:image/svg+xml;base64,[…]"`. This has two impacts. First, the size of the HTML code produced by this Graphviz plugin is much smaller. For example, the Base64 string for the Graphviz code `digraph graphname {a -> b -> c; b -> d;}` is four times smaller. Second, the Liquid Tags version generates a raster image file, whereas this Graphviz plugin produces a vector image that can be zoomed without image quality loss.
- Liquid Tags outputs the Graphviz image inside a `<span>`, whereas this Graphviz plugin offers a choice for the container element.
[Graphviz tag]: https://github.com/pelican-plugins/liquid-tags/blob/main/pelican/plugins/liquid_tags/graphviz.py
[Liquid Tags plugin]: https://github.com/pelican-plugins/liquid-tags
To-Do
-----
Contributions that make this plugin work with [reStructuredText][] content are welcome.
[reStructuredText]: https://docutils.sourceforge.io/rst.html
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/pelican-plugins/graphviz/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
Acknowledgments
---------------
Thanks to [Justin Mayer][], for helping with migration of this plugin under the Pelican Plugins organization, and to [Maxim Kochurov][], for introducing the `GRAPHVIZ_COMPRESS` configuration variable.
[Justin Mayer]: https://github.com/justinmayer
[Maxim Kochurov]: https://github.com/ferrine
Author
------
Copyright © 2015, 2021, 2023 Rafael Laboissière <rafael@laboissiere.net>
License
-------
This project is licensed under the terms of the AGPL 3.0 license.
Raw data
{
"_id": null,
"home_page": null,
"name": "pelican-graphviz",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8.1",
"maintainer_email": null,
"keywords": "pelican, plugin, graphviz",
"author": null,
"author_email": "=?utf-8?q?Rafael_Laboissi=C3=A8re?= <rafael@laboissiere.net>",
"download_url": "https://files.pythonhosted.org/packages/89/57/34dd96f5b8929b9ae5d0491b3a11b3dfc5c875ff84275efe5dfef4fa9290/pelican_graphviz-1.2.5.tar.gz",
"platform": null,
"description": "Graphviz: A Plugin for Pelican\n==============================\n\n[](https://github.com/pelican-plugins/graphviz/actions)\n[](https://pypi.org/project/pelican-graphviz/)\n\n\nGraphviz is a Pelican plugin that allows the inclusion of [Graphviz][] images using the Markdown markup format. The code for the Graphviz figure is included as a block in the article\u2019s source, and the image is embedded in HTML using the Base64 format.\n\n[Graphviz]: https://www.graphviz.org\n\n\nInstallation\n------------\n\nThis plugin can be installed via:\n\n python -m pip install pelican-graphviz\n\nGraphviz must be installed on the system, otherwise this plugin will be deactivated. Graphviz can be installed on Debian-based systems via:\n\n sudo aptitude install graphviz\n\nFor macOS, Graphviz can be installed via Homebrew:\n\n brew install graphviz\n\n\nUsage\n-----\n\nIn the Markdown source, the Graphviz code must be inserted as an individual block (i.e., separated from the rest of the material by blank lines), like the following:\n\n```markdwon\n..graphviz dot\ndigraph G {\n graph [rankdir = LR];\n Hello -> World\n}\n```\n\nThis will insert an image in your article like this:\n\n\n\nThe block must start with `..graphviz` (this is configurable \u2014 see below). The word `dot` in the first line indicates the program that will be run to produce the image. The available programs are: `dot`, `neato`, `twopi`, `circo`, `fdp`, `sfdp`, and `patchwork` (see the [Graphviz documentation][] for details). The Graphviz code must start in the second line of the block. Notice that *newlines are not allowed inside the Graphviz block*.\n\n[Graphviz documentation]: https://www.graphviz.org/documentation/\n\n\nStyling with CSS\n----------------\n\nThe image is generated in HTML with an `<img>` element inside an HTML element (by default a `<div>`, but this is configurable \u2014 see below). The latter has class `graphviz` (this is also configurable \u2014 see below). A possible CSS styling would be:\n\n```css\ndiv.graphviz {\n margin: 10px;\n}\ndiv.graphviz img {\n display: block;\n padding: 5px;\n margin-left: auto;\n margin-right: auto;\n text-align: center;\n border-style: solid;\n border-width: 1px;\n border-color: rgb(192, 177, 177);\n -webkit-border-radius: 5px;\n}\n```\n\n\nConfiguration\n-------------\n\nThe following variables can be set in the Pelican settings file:\n\n- `GRAPHVIZ_HTML_ELEMENT`: The HTML inside which the generated Graphviz image is inserted (defaults to `'div'`; another sensible possibility would be `'span'`).\n\n- `GRAPHVIZ_IMAGE_CLASS`: Class of the `<div>` element including the generated Graphviz image (defaults to `'graphviz'`).\n\n- `GRAPHVIZ_BLOCK_START`: Starting tag for the Graphviz block in Markdown (defaults to `'..graphviz'`).\n\n- `GRAPHVIZ_COMPRESS`: Compress the resulting SVG XML to an image (defaults to `True`). Without compression, more SVG features are available, for instance including clickable URLs inside the Graphviz diagram.\n\nThe values above can be overridden for each individual block using the syntax below:\n\n```markdwon\n..graphviz [key=val, ...] dot\n```\nThe allowed keys are `html-element`, `image-class`, and `compress`. For the latter, the value can be either `yes` or `no`.\n\n\nOutput Image Format\n-------------------\n\nThe format of the embedded image is SVG, and there is currently no way to change it. This format was chosen over others (like PNG) for two reasons. First, the generated SRC string in Base64 seem to be shorter for SVG than for PNG. Second, the image will be available in the browser in a high-quality vectorized format. As a caveat, notice that this choice may prevent display in browsers lacking proper SVG support.\n\n\nAlternatives\n------------\n\nAn alternative to this plugin is the [Graphviz tag][] provided by the [Liquid Tags plugin][], which differs from this plugin in several respects. First, the Liquid Tags version uses the syntax `{% graphviz { <program> [\u2026] } %}`, while this Graphviz plugin uses the Markdown extension syntax `..graphviz <program> [\u2026]`. Regarding the rendered output, the differences are:\n\n- Both plugins output an element with `class=\"graphviz\"`. However, only the Graphviz plugin allows you to change the class name via a configuration variable (`GRAPHVIZ_IMAGE_CLASS`).\n- Liquid Tags encodes the image as `src=\"data:image/png;base64,[\u2026]\"`, while the Graphviz plugin encodes it as `src=\"data:image/svg+xml;base64,[\u2026]\"`. This has two impacts. First, the size of the HTML code produced by this Graphviz plugin is much smaller. For example, the Base64 string for the Graphviz code `digraph graphname {a -> b -> c; b -> d;}` is four times smaller. Second, the Liquid Tags version generates a raster image file, whereas this Graphviz plugin produces a vector image that can be zoomed without image quality loss.\n- Liquid Tags outputs the Graphviz image inside a `<span>`, whereas this Graphviz plugin offers a choice for the container element.\n\n[Graphviz tag]: https://github.com/pelican-plugins/liquid-tags/blob/main/pelican/plugins/liquid_tags/graphviz.py\n[Liquid Tags plugin]: https://github.com/pelican-plugins/liquid-tags\n\n\nTo-Do\n-----\n\nContributions that make this plugin work with [reStructuredText][] content are welcome.\n\n[reStructuredText]: https://docutils.sourceforge.io/rst.html\n\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[existing issues]: https://github.com/pelican-plugins/graphviz/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\n\nAcknowledgments\n---------------\n\nThanks to [Justin Mayer][], for helping with migration of this plugin under the Pelican Plugins organization, and to [Maxim Kochurov][], for introducing the `GRAPHVIZ_COMPRESS` configuration variable.\n\n[Justin Mayer]: https://github.com/justinmayer\n[Maxim Kochurov]: https://github.com/ferrine\n\nAuthor\n------\n\nCopyright \u00a9 2015, 2021, 2023 Rafael Laboissi\u00e8re <rafael@laboissiere.net>\n\nLicense\n-------\n\nThis project is licensed under the terms of the AGPL 3.0 license.\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Pelican plugin supporting Graphviz images in articles",
"version": "1.2.5",
"project_urls": {
"Funding": "https://donate.getpelican.com/",
"Homepage": "https://github.com/pelican-plugins/graphviz",
"Issue tracker": "https://github.com/pelican-plugins/graphviz/issues"
},
"split_keywords": [
"pelican",
" plugin",
" graphviz"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86bab3cb0830972860fd1e10c3b5b512690e9110d49d8b5d30a59239dc61b31f",
"md5": "1d3c50592cdb8ea942cce79e3b634fea",
"sha256": "2309c718bddaf320cc9163dff804af13c4fbdc36433542b49aaac1f635c6e485"
},
"downloads": -1,
"filename": "pelican_graphviz-1.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d3c50592cdb8ea942cce79e3b634fea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8.1",
"size": 22522,
"upload_time": "2024-04-14T11:29:14",
"upload_time_iso_8601": "2024-04-14T11:29:14.446346Z",
"url": "https://files.pythonhosted.org/packages/86/ba/b3cb0830972860fd1e10c3b5b512690e9110d49d8b5d30a59239dc61b31f/pelican_graphviz-1.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "895734dd96f5b8929b9ae5d0491b3a11b3dfc5c875ff84275efe5dfef4fa9290",
"md5": "3475900219c7b8d36c290125abd6db31",
"sha256": "703495b00111a44424c924c01702857ecc76bfe39660f480c3a37f611ab48322"
},
"downloads": -1,
"filename": "pelican_graphviz-1.2.5.tar.gz",
"has_sig": false,
"md5_digest": "3475900219c7b8d36c290125abd6db31",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8.1",
"size": 30128,
"upload_time": "2024-04-14T11:29:16",
"upload_time_iso_8601": "2024-04-14T11:29:16.185792Z",
"url": "https://files.pythonhosted.org/packages/89/57/34dd96f5b8929b9ae5d0491b3a11b3dfc5c875ff84275efe5dfef4fa9290/pelican_graphviz-1.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 11:29:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pelican-plugins",
"github_project": "graphviz",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pelican-graphviz"
}
