markdown-kroki


Namemarkdown-kroki JSON
Version 0.1.0 PyPI version JSON
download
home_pageNone
SummaryDiagram extension for Python-Markdown using Kroki server.
upload_time2025-04-20 05:14:10
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseNone
keywords diagram markdown mermaid mkdocs plantuml
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # [markdown-kroki](https://hkato.github.io/markdown-kroki/)

Diagram extension for [Python-Markdown][python-markdown] using [Kroki server][kuroki].

This extension converts various 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 JavaScript, even during web browsing.

[mermaid]: https://mermaid.js.org/
[python-markdown]: https://python-markdown.github.io/
[kuroki]: https://kroki.io/
[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/

## Install

```sh
pip install git+https://github.com/hkato/markdown-kroki.git
```

## Requirements

### Internet access to the public Kroki server

Default setting with no options.

### Self-Managed Kroki server (recommended)

Here is a sample Docker Compose file.

ref. Kroki.io > [Install](https://kroki.io/#install) > [Using Docker or Podman](https://docs.kroki.io/kroki/setup/use-docker-or-podman/)

```sh
docker compose up -d
```

!!! note
    The default port used by MkDocs (`mkdocs serve`) may conflict with the default port of a Dockerized Kroki instance.
    Consequently, you will need to change the port configuration for one of them.

## Usage

### MkDocs Integration

```yaml
# mkdocs.yml
markdown_extensions:
  - markdown_kroki:
      kroki_url: http://localhost:18000  # default: https://kroki.io
```

### Python code

````python
import markdown
from markdown_kroki import KrokiDiagramExtension

markdown_text = """```plantuml image=svg width=300
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
@enduml
```"""

html_output = markdown.markdown(markdown_text, extensions=[
                                KrokiDiagramExtension(kroki_url='https://kroki.io')])

print(html_output)
````

```html
<p><img src="data:image/svg+xml;base64,PHN2ZyBhcmlhLXJvbGVkZXNjcmlwdGlvbj0ic2VxdWVuY2UiIHJvbGU
9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiB2aWV3Qm94PSItNTAgLTEwIDc1MCA1NzQiIHN0eWxlPSJtYXgtd2lkd
Gg6IDc1MHB4OyBiYWNrZ3JvdW5kLWNvbG9yOiB3aGl0ZTsiIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk
...
...
...
IHgxPSIyNzYiLz48L3N2Zz4=" ></p>
```

## Process flow

```mermaid
sequenceDiagram
    participant application as Application<br/>(eg MkDocs)
    participant markdown as Python Markdown
    participant extension as KrokiDiagramExtension
    participant engine as Kroki Server

    application->>markdown: Markdown + Diagrams
    markdown->>extension: Preprocessor
    extension->>engine: Diagram code 
    engine-->>engine: Convert
    engine-->>extension: Image Data
    extension-->>extension: Base64 encode
    extension-->>markdown: Markdown + data URI image
    markdown-->>application: HTML + data URI image
```

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "markdown-kroki",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "diagram, markdown, mermaid, mkdocs, plantuml",
    "author": null,
    "author_email": "Hideyuki KATO <hideyuki@kato.jp>",
    "download_url": "https://files.pythonhosted.org/packages/75/42/87d6243655f98a1e9dafd2413406b8223a5e5e5e5291601ac90e36195765/markdown_kroki-0.1.0.tar.gz",
    "platform": null,
    "description": "# [markdown-kroki](https://hkato.github.io/markdown-kroki/)\n\nDiagram extension for [Python-Markdown][python-markdown] using [Kroki server][kuroki].\n\nThis extension converts various diagram code blocks into Base64 encoded [data: URI][data-uri].\nThis enables PDF generation with tools like [MkDocs to PDF][mkdocs-to-pdf]/[WeasyPrint][wasyprint] without requiring JavaScript, even during web browsing.\n\n[mermaid]: https://mermaid.js.org/\n[python-markdown]: https://python-markdown.github.io/\n[kuroki]: https://kroki.io/\n[data-uri]: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data\n[mkdocs-to-pdf]: https://mkdocs-to-pdf.readthedocs.io/\n[wasyprint]: https://weasyprint.org/\n\n## Install\n\n```sh\npip install git+https://github.com/hkato/markdown-kroki.git\n```\n\n## Requirements\n\n### Internet access to the public Kroki server\n\nDefault setting with no options.\n\n### Self-Managed Kroki server (recommended)\n\nHere is a sample Docker Compose file.\n\nref. Kroki.io > [Install](https://kroki.io/#install) > [Using Docker or Podman](https://docs.kroki.io/kroki/setup/use-docker-or-podman/)\n\n```sh\ndocker compose up -d\n```\n\n!!! note\n    The default port used by MkDocs (`mkdocs serve`) may conflict with the default port of a Dockerized Kroki instance.\n    Consequently, you will need to change the port configuration for one of them.\n\n## Usage\n\n### MkDocs Integration\n\n```yaml\n# mkdocs.yml\nmarkdown_extensions:\n  - markdown_kroki:\n      kroki_url: http://localhost:18000  # default: https://kroki.io\n```\n\n### Python code\n\n````python\nimport markdown\nfrom markdown_kroki import KrokiDiagramExtension\n\nmarkdown_text = \"\"\"```plantuml image=svg width=300\n@startuml\nAlice -> Bob: Authentication Request\nBob --> Alice: Authentication Response\n@enduml\n```\"\"\"\n\nhtml_output = markdown.markdown(markdown_text, extensions=[\n                                KrokiDiagramExtension(kroki_url='https://kroki.io')])\n\nprint(html_output)\n````\n\n```html\n<p><img src=\"data:image/svg+xml;base64,PHN2ZyBhcmlhLXJvbGVkZXNjcmlwdGlvbj0ic2VxdWVuY2UiIHJvbGU\n9ImdyYXBoaWNzLWRvY3VtZW50IGRvY3VtZW50IiB2aWV3Qm94PSItNTAgLTEwIDc1MCA1NzQiIHN0eWxlPSJtYXgtd2lkd\nGg6IDc1MHB4OyBiYWNrZ3JvdW5kLWNvbG9yOiB3aGl0ZTsiIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk\n...\n...\n...\nIHgxPSIyNzYiLz48L3N2Zz4=\" ></p>\n```\n\n## Process flow\n\n```mermaid\nsequenceDiagram\n    participant application as Application<br/>(eg MkDocs)\n    participant markdown as Python Markdown\n    participant extension as KrokiDiagramExtension\n    participant engine as Kroki Server\n\n    application->>markdown: Markdown + Diagrams\n    markdown->>extension: Preprocessor\n    extension->>engine: Diagram code \n    engine-->>engine: Convert\n    engine-->>extension: Image Data\n    extension-->>extension: Base64 encode\n    extension-->>markdown: Markdown + data URI image\n    markdown-->>application: HTML + data URI image\n```\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Diagram extension for Python-Markdown using Kroki server.",
    "version": "0.1.0",
    "project_urls": {
        "Changelog": "https://github.com/hkato/markdown-kroki/blob/main/CHANGELOG.md",
        "Documentation": "https://hkato.github.io/markdown-kroki/",
        "Homepage": "https://github.com/hkato/markdown-kroki",
        "Issues": "https://github.com/hkato/markdown-kroki/issues",
        "Repository": "https://github.com/hkato/markdown-kroki"
    },
    "split_keywords": [
        "diagram",
        " markdown",
        " mermaid",
        " mkdocs",
        " plantuml"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "7cb1177d026ce15beba7ebdc4f83cfacd28c7bd613efc73a49155f0bbc82459a",
                "md5": "2729bc4e07162b08361a91b2dc04ff6f",
                "sha256": "3825e56424891266407370a310858759252ba7c03e85b4083251be210efccf86"
            },
            "downloads": -1,
            "filename": "markdown_kroki-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2729bc4e07162b08361a91b2dc04ff6f",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 5501,
            "upload_time": "2025-04-20T05:14:08",
            "upload_time_iso_8601": "2025-04-20T05:14:08.555295Z",
            "url": "https://files.pythonhosted.org/packages/7c/b1/177d026ce15beba7ebdc4f83cfacd28c7bd613efc73a49155f0bbc82459a/markdown_kroki-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "754287d6243655f98a1e9dafd2413406b8223a5e5e5e5291601ac90e36195765",
                "md5": "ba7a2d0c184e83e38950a33745fd1de7",
                "sha256": "6490a643b7f84368f0016d9e9cfe9b0f5945fe717b56d52ba23a3b1615acd258"
            },
            "downloads": -1,
            "filename": "markdown_kroki-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "ba7a2d0c184e83e38950a33745fd1de7",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 78101,
            "upload_time": "2025-04-20T05:14:10",
            "upload_time_iso_8601": "2025-04-20T05:14:10.031224Z",
            "url": "https://files.pythonhosted.org/packages/75/42/87d6243655f98a1e9dafd2413406b8223a5e5e5e5291601ac90e36195765/markdown_kroki-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-04-20 05:14:10",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "hkato",
    "github_project": "markdown-kroki",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "markdown-kroki"
}
        
Elapsed time: 0.81161s