mermaid-ascii (PyPI packaging)

This repository rebundles the upstream mermaid-ascii (written in Go) and publishes it to PyPI as a Python package. It exists to make Mermaid → ASCII conversion trivial to install and use from Python and in CI, without requiring Node, Graphviz, or a JVM.

Upstream author: Alexander Grooff This repo is a packaging/redistribution project and is not affiliated with the upstream authors.

---

What you get

• A prebuilt mermaid-ascii binary shipped inside the wheel.
• A tiny Python wrapper for programmatic use (mermaid_to_ascii(...)).
• Optional CLI access via your Python environment (see Usage).

This lets you:

• Convert Mermaid diagrams to ASCII in terminals and CI logs
• Call the converter directly from Python, Jupyter, or scripts

---

Install

pip install mermaid-ascii

We publish wheels for common platforms. If a wheel isn’t available for your platform yet, please open an issue.

---

Quick start

CLI

# From a file
mermaid-ascii -i diagram.mmd

# From stdin
echo 'flowchart LR; A-->B' | mermaid-ascii -i -

Python API

from mermaid_ascii import mermaid_to_ascii

src = """
flowchart TB
  A[Start] --> B{Question?}
  B -->|Yes| C[Go]
  B -->|No|  D[Stop]
"""
print(mermaid_to_ascii(src))

Jupyter tip

JupyterLab ≥ 4.1 / Notebook ≥ 7.1 can render Mermaid natively for visual preview:

```mermaid
flowchart LR
  A --> B
```

Use this package when you specifically need ASCII output (for terminals, logs, or text-only artifacts).

---

Versioning

• The Python package version matches the upstream mermaid-ascii tag, with a leading v stripped if present (e.g., upstream v0.6.1 → package 0.6.1).
• Each release of this package corresponds to the latest upstream release at the time of packaging.

---

How this repo works (release automation)

1. CI clones the upstream AlexanderGrooff/mermaid-ascii repo and detects its latest tag.

2. If that version differs from this package’s version in pyproject.toml (annotated with # mermaid-ascii version), CI:

   • Updates pyproject.toml to the new version
   • Builds the upstream Go binary
   • Bundles the binary into the Python wheel
   • Publishes to PyPI
   • Creates a GitHub tag + release in this repo

3. If nothing changed, CI exits without publishing.

This keeps the PyPI package in lockstep with upstream releases.

---

Platforms

We aim to provide wheels for:

• Linux (x86_64, aarch64)
• macOS (arm64, x86_64)
• Windows (x86_64)

If your platform isn’t covered, please open an issue with details (OS, architecture, Python version).

---

Troubleshooting

• mermaid-ascii: command not found Ensure your Python environment’s bin/Scripts is on PATH. Alternatively, invoke via Python:

  python -m mermaid_ascii -i diagram.mmd

  (If unavailable, use the Python API example above.)

• Non-ASCII terminals Output uses Unicode box-drawing characters. If your terminal can’t display them, switch to a UTF-8–capable font/locale.

• Diagram doesn’t render as expected Please first confirm the diagram renders in a Mermaid viewer. If the ASCII rendering is the problem, open an issue here; if it’s Mermaid syntax/semantics, consider filing upstream.

---

Contributing

• Packaging changes and Python wrapper issues → this repo
• Core ASCII rendering behavior → upstream: https://github.com/AlexanderGrooff/mermaid-ascii

PRs are welcome for:

• Additional wheels/platforms
• CI improvements
• Small Python wrapper enhancements (docs, examples)

---

License & attribution

• The included mermaid-ascii binary and its source are licensed by the upstream project.
• The packaging code in this repository is licensed as stated in this repo’s LICENSE file.
• © Respect to the upstream author(s). This project simply repackages their work for PyPI distribution.

---

Maintainers

• Open Science Labs – OSL Packages Repo: https://github.com/osl-packages/mermaid-ascii

If you rely on this package, consider starring both this repo and the upstream to support the maintainers.