# pandoc-mermaid-selenium-filter
[](https://pypi.org/project/pandoc-mermaid-selenium-filter/)
[](https://pypi.org/project/pandoc-mermaid-selenium-filter/)
[](https://github.com/itTkm/pandoc-mermaid-selenium-filter/blob/main/LICENSE)
[](https://github.com/itTkm/pandoc-mermaid-selenium-filter/actions/workflows/test.yml?query=branch%3Amain)
[](https://coveralls.io/github/itTkm/pandoc-mermaid-selenium-filter?branch=main)
Provides a feature available as a [filter] for the widely known universal document conversion tool [Pandoc], which converts code blocks written in [Mermaid] syntax within Markdown documents into images.
Supports [Architecture Diagrams] introduced in Mermaid v11.1.0. Additionally, icon sets from [iconify.design], including [SVG Logos] and [Material Design Icons], are available for use.
The conversion process follows these steps:
1. Detect code blocks with the `mermaid` class specified
2. Convert the detected Mermaid syntax code to PNG images using [Selenium]
3. Save the generated images in the `mermaid-images` directory and replace the original code blocks with image references
Although many similar filters with the same functionality are already available, most of them rely on packages using [Puppeteer] as the image conversion engine. These packages often face dependency issues or have challenges related to complex setup and configuration. This package adopts [Selenium], which has a longer history than Puppeteer.
> [!NOTE]
>
> - [Chrome WebDriver] will be downloaded on first execution
> - A headless Chrome browser is temporarily used for image generation
[pandoc]: https://pandoc.org/
[filter]: https://pandoc.org/filters.html
[Mermaid]: https://mermaid.js.org/
[Architecture Diagrams]: https://mermaid.js.org/syntax/architecture.html
[iconify.design]: https://iconify.design/
[SVG Logos]: https://icon-sets.iconify.design/logos/
[Material Design Icons]: https://icon-sets.iconify.design/mdi/
[Selenium]: https://www.selenium.dev/
[Puppeteer]: https://pptr.dev/
[Chrome WebDriver]: (https://developer.chrome.com/docs/chromedriver?hl=ja)
## Usage
1. First, install the filter.
```bash
pip install pandoc-mermaid-selenium-filter
```
2. When using Mermaid syntax in your Markdown file, use a code block with the `mermaid` class specified as follows:
````markdown
# Testing Mermaid Filter
Here's a simple flowchart example:
```mermaid
graph TD
A[Start] --> B{Condition}
B -->|Yes| C[Process 1]
B -->|No| D[Process 2]
C --> E[End]
D --> E
```
````
3. You can convert Markdown to HTML/PDF using the following commands:
```bash
# HTML
pandoc example/example.md \
--filter pandoc-mermaid-selenium-filter \
-o example/output.html
# PDF
pandoc example/example.md \
--filter pandoc-mermaid-selenium-filter \
-o example/output.pdf
```
> [!NOTE]
>
> For generating PDFs with Japanese text, add the following options.
> Note that you need to install `collection-langjapanese` beforehand to add Japanese support to Pandoc.
>
> ```bash
> pandoc example/example.md \
> --filter pandoc-mermaid-selenium-filter \
> -o example/output.pdf \
> --pdf-engine lualatex \
> -V documentclass=ltjarticle \
> -V luatexjapresetoptions=fonts-noto-cjk
> ```
## Architecture Diagrams
In the context of mermaid-js, the architecture diagram is used to show the relationship between services and resources commonly found within the Cloud or CI/CD deployments. In an architecture diagram, services (nodes) are connected by edges. Related services can be placed within groups to better illustrate how they are organized.
The example code as follows:
````markdown
```mermaid
architecture-beta
group api(cloud)[API]
service db(database)[Database] in api
service disk1(disk)[Storage] in api
service disk2(disk)[Storage] in api
service server(server)[Server] in api
db:L -- R:server
disk1:T -- B:server
disk2:T -- B:db
```
````
## Icons
By default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`. This package provides access to the [SVG Logos] and [Material Design Icons] icon sets offered by [iconify.design]. They can be used in the architecture diagram by using the format `logos:icon-name` or `mdi:icon-name`.
The example code will change as follows:
````markdown
```mermaid
architecture-beta
group api(logos:aws-lambda)[API]
service db(logos:aws-aurora)[Database] in api
service disk1(logos:aws-glacier)[Storage] in api
service disk2(logos:aws-s3)[Storage] in api
service server(logos:aws-ec2)[Server] in api
db:L -- R:server
disk1:T -- B:server
disk2:T -- B:db
```
````
## Developer Information
### Development Environment Setup
You can install all development dependencies with the following command:
```bash
uv sync --extra dev
```
### Build
You can build this package using the following command. During the build process, the custom hooks will download the latest source code for [Mermaid], as well as the [SVG Logos] and [Material Design Icons] icon sets, from [jsDelivr].
[jsDelivr]: https://www.jsdelivr.com/
```bash
uv build
```
### Testing
You can run tests with the following command:
```bash
uv run pytest
```
## License
This library is licensed under the [MIT License](https://github.com/itTkm/pandoc-mermaid-selenium-filter/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "pandoc-mermaid-selenium-filter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "filter, markdown, mermaid, pandoc, selenium",
"author": "itTkm",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b0/9e/a68ee97cd0f8342012929e73a84cd4b5b0c6ea7ba32f54259bac51337346/pandoc_mermaid_selenium_filter-1.0.1.tar.gz",
"platform": null,
"description": "# pandoc-mermaid-selenium-filter\n\n[](https://pypi.org/project/pandoc-mermaid-selenium-filter/)\n[](https://pypi.org/project/pandoc-mermaid-selenium-filter/)\n[](https://github.com/itTkm/pandoc-mermaid-selenium-filter/blob/main/LICENSE)\n[](https://github.com/itTkm/pandoc-mermaid-selenium-filter/actions/workflows/test.yml?query=branch%3Amain)\n[](https://coveralls.io/github/itTkm/pandoc-mermaid-selenium-filter?branch=main)\n\nProvides a feature available as a [filter] for the widely known universal document conversion tool [Pandoc], which converts code blocks written in [Mermaid] syntax within Markdown documents into images.\n\nSupports [Architecture Diagrams] introduced in Mermaid v11.1.0. Additionally, icon sets from [iconify.design], including [SVG Logos] and [Material Design Icons], are available for use.\n\nThe conversion process follows these steps:\n\n1. Detect code blocks with the `mermaid` class specified\n2. Convert the detected Mermaid syntax code to PNG images using [Selenium]\n3. Save the generated images in the `mermaid-images` directory and replace the original code blocks with image references\n\nAlthough many similar filters with the same functionality are already available, most of them rely on packages using [Puppeteer] as the image conversion engine. These packages often face dependency issues or have challenges related to complex setup and configuration. This package adopts [Selenium], which has a longer history than Puppeteer.\n\n> [!NOTE]\n>\n> - [Chrome WebDriver] will be downloaded on first execution\n> - A headless Chrome browser is temporarily used for image generation\n\n[pandoc]: https://pandoc.org/\n[filter]: https://pandoc.org/filters.html\n[Mermaid]: https://mermaid.js.org/\n[Architecture Diagrams]: https://mermaid.js.org/syntax/architecture.html\n[iconify.design]: https://iconify.design/\n[SVG Logos]: https://icon-sets.iconify.design/logos/\n[Material Design Icons]: https://icon-sets.iconify.design/mdi/\n[Selenium]: https://www.selenium.dev/\n[Puppeteer]: https://pptr.dev/\n[Chrome WebDriver]: (https://developer.chrome.com/docs/chromedriver?hl=ja)\n\n## Usage\n\n1. First, install the filter.\n\n ```bash\n pip install pandoc-mermaid-selenium-filter\n ```\n\n2. When using Mermaid syntax in your Markdown file, use a code block with the `mermaid` class specified as follows:\n\n ````markdown\n # Testing Mermaid Filter\n\n Here's a simple flowchart example:\n\n ```mermaid\n graph TD\n A[Start] --> B{Condition}\n B -->|Yes| C[Process 1]\n B -->|No| D[Process 2]\n C --> E[End]\n D --> E\n ```\n ````\n\n3. You can convert Markdown to HTML/PDF using the following commands:\n\n ```bash\n # HTML\n pandoc example/example.md \\\n --filter pandoc-mermaid-selenium-filter \\\n -o example/output.html\n\n # PDF\n pandoc example/example.md \\\n --filter pandoc-mermaid-selenium-filter \\\n -o example/output.pdf\n ```\n\n> [!NOTE]\n>\n> For generating PDFs with Japanese text, add the following options.\n> Note that you need to install `collection-langjapanese` beforehand to add Japanese support to Pandoc.\n>\n> ```bash\n> pandoc example/example.md \\\n> --filter pandoc-mermaid-selenium-filter \\\n> -o example/output.pdf \\\n> --pdf-engine lualatex \\\n> -V documentclass=ltjarticle \\\n> -V luatexjapresetoptions=fonts-noto-cjk\n> ```\n\n## Architecture Diagrams\n\nIn the context of mermaid-js, the architecture diagram is used to show the relationship between services and resources commonly found within the Cloud or CI/CD deployments. In an architecture diagram, services (nodes) are connected by edges. Related services can be placed within groups to better illustrate how they are organized.\n\nThe example code as follows:\n\n````markdown\n```mermaid\narchitecture-beta\n group api(cloud)[API]\n\n service db(database)[Database] in api\n service disk1(disk)[Storage] in api\n service disk2(disk)[Storage] in api\n service server(server)[Server] in api\n\n db:L -- R:server\n disk1:T -- B:server\n disk2:T -- B:db\n```\n````\n\n## Icons\n\nBy default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`. This package provides access to the [SVG Logos] and [Material Design Icons] icon sets offered by [iconify.design]. They can be used in the architecture diagram by using the format `logos:icon-name` or `mdi:icon-name`.\n\nThe example code will change as follows:\n\n````markdown\n```mermaid\narchitecture-beta\n group api(logos:aws-lambda)[API]\n\n service db(logos:aws-aurora)[Database] in api\n service disk1(logos:aws-glacier)[Storage] in api\n service disk2(logos:aws-s3)[Storage] in api\n service server(logos:aws-ec2)[Server] in api\n\n db:L -- R:server\n disk1:T -- B:server\n disk2:T -- B:db\n```\n````\n\n## Developer Information\n\n### Development Environment Setup\n\nYou can install all development dependencies with the following command:\n\n```bash\nuv sync --extra dev\n```\n\n### Build\n\nYou can build this package using the following command. During the build process, the custom hooks will download the latest source code for [Mermaid], as well as the [SVG Logos] and [Material Design Icons] icon sets, from [jsDelivr].\n\n[jsDelivr]: https://www.jsdelivr.com/\n\n```bash\nuv build\n```\n\n### Testing\n\nYou can run tests with the following command:\n\n```bash\nuv run pytest\n```\n\n## License\n\nThis library is licensed under the [MIT License](https://github.com/itTkm/pandoc-mermaid-selenium-filter/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "A Pandoc filter that converts Mermaid code blocks to images using Selenium",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/itTkm/pandoc-mermaid-selenium-filter",
"Issues": "https://github.com/itTkm/pandoc-mermaid-selenium-filter/issues",
"Repository": "https://github.com/itTkm/pandoc-mermaid-selenium-filter.git"
},
"split_keywords": [
"filter",
" markdown",
" mermaid",
" pandoc",
" selenium"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a85c1e90475f08fb0305fe8a3ee155a240832867c197f2b39128d942ae1ddc5e",
"md5": "5828ce882b480f5f3901e70fcce4511d",
"sha256": "1423491d364de75ce33f136f425241260e7d28ae5db7739a279c5bce7b125fef"
},
"downloads": -1,
"filename": "pandoc_mermaid_selenium_filter-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5828ce882b480f5f3901e70fcce4511d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4176720,
"upload_time": "2025-01-27T10:40:03",
"upload_time_iso_8601": "2025-01-27T10:40:03.024937Z",
"url": "https://files.pythonhosted.org/packages/a8/5c/1e90475f08fb0305fe8a3ee155a240832867c197f2b39128d942ae1ddc5e/pandoc_mermaid_selenium_filter-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b09ea68ee97cd0f8342012929e73a84cd4b5b0c6ea7ba32f54259bac51337346",
"md5": "d2f3b30859503b45075a93f5312aca74",
"sha256": "7c5947c2b1dace5c85e1d2cd95f704223514f7bcfe115501315f3f2c63f88c4f"
},
"downloads": -1,
"filename": "pandoc_mermaid_selenium_filter-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d2f3b30859503b45075a93f5312aca74",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 4164339,
"upload_time": "2025-01-27T10:40:05",
"upload_time_iso_8601": "2025-01-27T10:40:05.625424Z",
"url": "https://files.pythonhosted.org/packages/b0/9e/a68ee97cd0f8342012929e73a84cd4b5b0c6ea7ba32f54259bac51337346/pandoc_mermaid_selenium_filter-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-27 10:40:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "itTkm",
"github_project": "pandoc-mermaid-selenium-filter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pandoc-mermaid-selenium-filter"
}
JSON
