https://github.com/hkato/markdown-mermaid-cli
Mermaid extension for Python-Markdown using mermaid-cli.
https://github.com/hkato/markdown-mermaid-cli
diagram markdown mermaid mkdocs
Last synced: 4 months ago
JSON representation
Mermaid extension for Python-Markdown using mermaid-cli.
- Host: GitHub
- URL: https://github.com/hkato/markdown-mermaid-cli
- Owner: hkato
- License: mit
- Created: 2025-04-13T07:54:37.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-20T22:38:20.000Z (7 months ago)
- Last Synced: 2025-11-20T23:19:06.697Z (7 months ago)
- Topics: diagram, markdown, mermaid, mkdocs
- Language: Python
- Homepage: https://hkato.github.io/markdown-mermaid-cli/
- Size: 176 KB
- Stars: 4
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# [markdown-mermaid-cli](https://hkato.github.io/markdown-mermaid-cli/)
[](https://pypi.org/project/markdown-mermaid-cli/)
[Mermaid][mermaid] extension for [Python-Markdown][python-markdown] using [Mermaid-CLI][mermaid-cli].
This extension converts Mermaid diagram code blocks into Base64 encoded [data: URI][data-uri].
This enables PDF generation with tools like [MkDocs to PDF][mkdocs-to-pdf]/[WeasyPrint][wasyprint]
without requiring client-side JavaScript.
## Install
```sh
pip install markdown-mermaid-cli
```
## Requirements
### Mermaid CLI
> Chrome or Chromium is required to run Mermaid-CLI.
```sh
npm install @mermaid-js/mermaid-cli
```
or
```sh
npm install --global @mermaid-js/mermaid-cli
```
## Usage
- code block start with ```mermaid
- code block end with ```
options:
```markdown
formant=[svg|png] {img attribute}="value" {cli option}="value"`
```
- format (optional): Output image format (defaults to svg)
- img attribute (optional): alt, width, height, class, id, style, title
- cli option (optional): theme, width, height, backgroundColor, svgId, scale (refer to `mmdc -h`)
### [MkDocs][mkdocs] Integration
```yaml
# mkdocs.yml
markdown_extensions:
- markdown_mermaid_cli
```
or with options:
```yaml
# mkdocs.yml
markdown_extensions:
- markdown_mermaid_cli:
default_format: png # svg or png, default svg
```
### [Pelican][pelican] Integration
```py
# pelicanconf.py
MARKDOWN = {
'extension_configs': {
'markdown.extensions.codehilite': {'css_class': 'highlight'},
'markdown.extensions.extra': {},
'markdown_mermaid_cli': {}, # Add this
},
'output_format': 'html5',
}
```
### Python code
````python
import markdown
from markdown_mermaid_cli import MermaidExtension
markdown_text = """```mermaid
sequenceDiagram
participant Alice
participant Bob
Bob->>Alice: Hi Alice
Alice->>Bob: Hi Bob
```"""
html_output = markdown.markdown(
markdown_text, extensions=[MermaidExtension()]
)
print(html_output)
````
```html
![]()
```
## Process flow
```mermaid
sequenceDiagram
participant application as Application
(eg MkDocs)
participant markdown as Python Markdown
participant extension as MermaidDataURIExtension
participant engine as Mermaid CLI
application->>markdown: Markdown + Mermaid
markdown->>extension: Preprocessor
extension->>engine: Mermaid
engine-->>engine: Convert
engine-->>extension: Image Data
extension-->>extension: Base64 encode
extension-->>markdown: Markdown + data URI image
markdown-->>application: HTML + data URI image
```
[mermaid]: https://mermaid.js.org/
[python-markdown]: https://python-markdown.github.io/
[mermaid-cli]: https://github.com/mermaid-js/mermaid-cli
[data-uri]: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data
[mkdocs-to-pdf]: https://mkdocs-to-pdf.readthedocs.io/
[wasyprint]: https://weasyprint.org/
[mkdocs]: https://www.mkdocs.org/
[pelican]: https://getpelican.com/