{"id":9097,"library":"markdown-inline-graphviz-extension","title":"Markdown Inline Graphviz Extension","description":"The `markdown-inline-graphviz-extension` library is a Python Markdown extension that allows rendering of Graphviz DOT language diagrams directly within Markdown documents, replacing inline definitions with inline SVG or PNG images. It is a Python 3 fork and continuation of previous projects, designed to work seamlessly with any Python-Markdown-based static site generator. Its current version is 1.1.3, with updates occurring on an as-needed basis to ensure compatibility and address issues.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/cesaremorel/markdown-inline-graphviz","tags":["markdown","graphviz","documentation","visualization","static site","extension"],"install":[{"cmd":"pip install markdown-inline-graphviz-extension","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"Required for parsing Markdown text and integrating the extension.","package":"markdown"},{"reason":"The Python binding for Graphviz, used to generate graph data from DOT language.","package":"graphviz"},{"reason":"The underlying Graphviz executable (e.g., 'dot', 'neato') must be installed on the system and available in the PATH for graphs to be rendered. This is a crucial external dependency, not a Python package.","package":"Graphviz (system installation)","optional":true}],"imports":[{"note":"This library is primarily used as a string-based extension for the `markdown` library, not via a direct Python import of a class or function by users. The correct string name to use in the extensions list is 'markdown_inline_graphviz'.","wrong":"from markdown_inline_graphviz_extension import InlineGraphvizExtension","symbol":"Extension String","correct":"import markdown\nhtml = markdown.markdown(text, extensions=['markdown_inline_graphviz'])"}],"quickstart":{"code":"import markdown\nimport os\n\n# Ensure Graphviz 'dot' executable is in your system's PATH\n# For example, on Ubuntu/Debian: sudo apt-get install graphviz\n# On macOS: brew install graphviz\n\nmarkdown_text = \"\"\"\n# My Document with a Graph\n\nHere is a simple graph:\n\n{% dot example.svg\ndigraph G {\n    A -> B;\n    B -> C;\n    C -> A;\n}\n%}\n\nAnother graph using a different engine:\n\n{% neato another.svg\nnode [shape=box];\nA -- B;\nB -- C;\nC -- A;\n%}\n\n\"\"\"\n\n# Render the markdown with the inline_graphviz extension\n# Ensure the extension name is exactly 'markdown_inline_graphviz'\ntry:\n    html_output = markdown.markdown(markdown_text, extensions=['markdown_inline_graphviz'])\n    print(html_output)\nexcept Exception as e:\n    print(f\"Error rendering markdown: {e}\")\n    print(\"Please ensure Graphviz is installed on your system and its executables are in your PATH.\")\n    print(\"You can test by running 'dot -V' or 'neato -V' in your terminal.\")\n","lang":"python","description":"This quickstart demonstrates how to parse Markdown text containing inline Graphviz definitions using the `markdown_inline_graphviz` extension and print the resulting HTML. It is crucial to have the Graphviz 'dot' executable (and other layout engines like 'neato') installed on your system and available in your system's PATH for this extension to function correctly. The example includes both `dot` and `neato` graph definitions."},"warnings":[{"fix":"Install Graphviz via your system's package manager (e.g., `sudo apt-get install graphviz` on Debian/Ubuntu, `brew install graphviz` on macOS) or download from graphviz.org, and ensure its executables are in your system's PATH. Verify installation by running `dot -V` or `neato -V` in your terminal.","message":"The underlying `graphviz` Python package (a dependency) requires the Graphviz `dot` executable and other layout engines (e.g., `neato`, `fdp`) to be installed on your system and available in the system's PATH. Without these system executables, the extension will fail to render graphs, potentially with errors from the `graphviz` Python library or simply outputting empty placeholders.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `extensions=['markdown_inline_graphviz']` is used exactly as shown in your `markdown.markdown` call or `mkdocs.yml` configuration.","message":"The correct extension string to use with `markdown.markdown()` is `'markdown_inline_graphviz'`. Incorrect spelling or capitalization (e.g., `inline_graphviz`, `Markdown_Inline_Graphviz`, `markdown_graphviz_inline`) will prevent the extension from loading and processing graph blocks, leading to unrendered graph definitions in your output HTML.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify behavior with existing markdown files and ensure your environment is Python 3. If upgrading from very old versions, test thoroughly. Review release notes for specific 'Markdown 3 compatibility' fixes in versions like 1.1.3 and 1.1.1.","message":"This `markdown-inline-graphviz-extension` library is a Python 3 fork and continuation of the original `markdown-inline-graphviz` (by Steffen Prince, `sprin/markdown-inline-graphviz`). While core functionality is similar, users migrating from the older Python 2-compatible libraries should be aware of potential subtle behavioral differences or changes in required `markdown` library versions. The library explicitly targets Python 3 environments.","severity":"breaking","affected_versions":"<1.0.0 (older forks) vs. >=1.0.0 (current)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Correct the extension name to `markdown_inline_graphviz`. For MkDocs, this would be in `mkdocs.yml` under `markdown_extensions: - markdown_inline_graphviz`.","cause":"The extension name provided in the configuration (e.g., `mkdocs.yml` or the `extensions` list) is incorrect or misspelled.","error":"ERROR - Config value: 'markdown_extensions'. Error: Failed loading extension \"inline_graphviz\". Aborted with 1 Configuration Errors!"},{"fix":"Install Graphviz on your system. For Debian/Ubuntu: `sudo apt-get install graphviz`. For macOS: `brew install graphviz`. For Windows, download from graphviz.org. Ensure the installation directory is added to your system's PATH.","cause":"The Graphviz system executables (like `dot`, `neato`, etc.) are not installed on your operating system or are not accessible via your system's PATH environment variable. The Python `graphviz` library, which `markdown-inline-graphviz-extension` uses, relies on these external tools.","error":"Error: Failed to execute dot. Verify that Graphviz is installed and in your system's PATH. (or similar errors like 'dot not found', 'neato not found')"},{"fix":"If a graph fails to render, carefully check your DOT language syntax. Clear any build caches or temporary output directories that the Markdown processor might use. If manually debugging, run the `dot` command with your graph definition directly in the terminal to identify syntax errors before integrating with Markdown.","cause":"Graphviz errors within the DOT code might be reported only once by the underlying `graphviz` tool, and subsequent builds might reuse old cached images or fail silently. This can lead to a misleading state where changes aren't reflected or errors are hard to debug.","error":"Graphs are not rendered, or outdated graphs are displayed, even after fixing the DOT code."}]}