{"id":16398368,"url":"https://github.com/raphaelmansuy/mermaidpix","last_synced_at":"2025-05-13T01:14:53.720Z","repository":{"id":250330689,"uuid":"833964798","full_name":"raphaelmansuy/mermaidpix","owner":"raphaelmansuy","description":"MermaidPix bridges this gap by automatically converting Mermaid diagrams in your Markdown files into high-resolution PNG images","archived":false,"fork":false,"pushed_at":"2024-09-23T07:15:55.000Z","size":446,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-13T01:14:46.239Z","etag":null,"topics":["cli","markdown","mermaid","tools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raphaelmansuy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-26T06:19:58.000Z","updated_at":"2025-01-16T18:00:45.000Z","dependencies_parsed_at":"2024-07-26T16:30:18.522Z","dependency_job_id":"0e802628-4bfc-4d75-a184-8ab2a323bb85","html_url":"https://github.com/raphaelmansuy/mermaidpix","commit_stats":null,"previous_names":["raphaelmansuy/mermaidpix"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fmermaidpix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fmermaidpix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fmermaidpix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelmansuy%2Fmermaidpix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raphaelmansuy","download_url":"https://codeload.github.com/raphaelmansuy/mermaidpix/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253851074,"owners_count":21973674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","markdown","mermaid","tools"],"created_at":"2024-10-11T05:12:31.539Z","updated_at":"2025-05-13T01:14:53.696Z","avatar_url":"https://github.com/raphaelmansuy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MermaidPix\n\n## Why MermaidPix?\n\nIn the world of technical documentation and diagramming, Mermaid has become an invaluable tool for creating clear, version-controllable diagrams using simple text-based syntax. However, sharing these diagrams outside of Markdown-rendering environments or in high-resolution formats can be challenging.\n\n**MermaidPix** bridges this gap by automatically converting Mermaid diagrams in your Markdown files into high-resolution PNG images. This tool ensures that your diagrams are:\n\n1. Easily shareable in any context.\n2. Rendered in high quality for presentations or publications.\n3. Consistently generated, allowing for version control of both the diagram code and the resulting image.\n\n## What is MermaidPix?\n\nMermaidPix is a Python-based command-line tool that:\n\n1. Scans Markdown files for Mermaid diagram code blocks.\n2. Converts each Mermaid diagram to a high-resolution PNG image.\n3. Replaces the Mermaid code in the Markdown with a link to the generated image.\n4. Maintains idempotency by generating consistent filenames based on diagram content.\n\n### Key Features\n\n- High-resolution output (4K) with transparent backgrounds.\n- Deterministic file naming for easy version control.\n- Efficient processing with caching of previously generated images.\n- Verbose logging option for detailed conversion information.\n\n## How to Use MermaidPix\n\n### Prerequisites\n\n1. Python 3.7 or higher.\n2. pipx (for installing Python applications globally).\n3. Poetry (for dependency management and packaging).\n4. Mermaid CLI (mmdc).\n\n### Installation\n\n#### Step 1: Install pipx\n\nIf you haven't installed pipx yet, you can do so using pip:\n\n```bash\npip install --user pipx\npipx ensurepath\n```\n\nInstall using Pypi:\n\n```bash\npipx install mermaidpix\n```\n\n#### Step 2: Install Poetry\n\nUse pipx to install Poetry:\n\n```bash\npipx install poetry\n```\n\n#### Step 3: Install Mermaid CLI\n\nInstall Mermaid CLI globally using npm:\n\n```bash\nnpm install -g @mermaid-js/mermaid-cli\n```\n\n#### Step 4: Install MermaidPix\n\nClone the repository and install MermaidPix using Poetry:\n\n```bash\ngit clone https://github.com/raphaelmansuy/mermaidpix.git\ncd mermaidpix\npoetry install\n```\n\nThis will create a virtual environment and install all the necessary dependencies.\n\n### Usage\n\nTo use MermaidPix, you can run it directly through Poetry:\n\n```bash\npoetry run python mermaid_pix/main.py \u003cinput_file\u003e \u003coutput_file\u003e [-v]\n```\n\nAlternatively, you can activate the Poetry shell and run the script:\n\n```bash\npoetry shell\npython mermaid_pix/main.py \u003cinput_file\u003e \u003coutput_file\u003e [-v]\n```\n\n#### Command Line Arguments\n\n- `\u003cinput_file\u003e`: Path to the input Markdown file.\n- `\u003coutput_file\u003e`: Path where the processed Markdown file will be saved.\n- `-v` or `--verbose`: (Optional) Enable verbose logging.\n\n### Example\n\n```bash\npoetry run python mermaid_pix/main.py docs/architecture.md docs/architecture_with_images.md -v\n```\n\nThis command will:\n\n1. Read `docs/architecture.md`.\n2. Convert any Mermaid diagrams to PNGs and save them in the same directory as the output file.\n3. Create a new file `docs/architecture_with_images.md` with image links replacing Mermaid code blocks.\n4. Provide verbose output of the conversion process.\n\n### Example Input and Output\n\n**Input Markdown (`input.md`):**\n\n```markdown\n# System Architecture\n\nHere's our current system architecture:\n\n\ngraph TD\n    A[Client] --\u003e|HTTP Request| B(Load Balancer)\n    B --\u003e|Forward| C{Web Server}\n    C --\u003e|Query| D[(Database)]\n    C --\u003e|Cache| E((Redis))\n\n\nThis diagram shows the basic flow of our system.\n```\n\n**After running MermaidPix:**\n\n```bash\npoetry run python mermaid_pix/main.py input.md output.md\n```\n\n**Output Markdown (`output.md`):**\n\n```markdown\n# System Architecture\n\nHere's our current system architecture:\n\n![Mermaid Diagram](images/diagrams/mermaid_\u003chash\u003e.png)\n\nThis diagram shows the basic flow of our system.\n```\n\nThe Mermaid diagram is now converted to a high-resolution PNG image, making it easily viewable in any Markdown reader or web browser.\n\n## Development\n\nTo set up MermaidPix for development:\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/yourusername/mermaidpix.git\n   cd mermaidpix\n   ```\n\n2. Install dependencies:\n   ```bash\n   poetry install\n   ```\n\n3. Activate the virtual environment:\n   ```bash\n   poetry shell\n   ```\n\n4. Make your changes and run tests:\n   ```bash\n   poetry run pytest\n   ```\n\n## Contributing\n\nWe welcome contributions to MermaidPix! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to submit pull requests, report issues, or request features.\n\n## License\n\nMermaidPix is released under the MIT License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelmansuy%2Fmermaidpix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraphaelmansuy%2Fmermaidpix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelmansuy%2Fmermaidpix/lists"}