Markdown Inline Graphviz Extension

Common errors

• ERROR - Config value: 'markdown_extensions'. Error: Failed loading extension "inline_graphviz". Aborted with 1 Configuration Errors!

  cause The extension name provided in the configuration (e.g., `mkdocs.yml` or the `extensions` list) is incorrect or misspelled.
  fix Correct the extension name to `markdown_inline_graphviz`. For MkDocs, this would be in `mkdocs.yml` under `markdown_extensions: - markdown_inline_graphviz`.

• 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')

  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.
  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.

• Graphs are not rendered, or outdated graphs are displayed, even after fixing the DOT code.

  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.
  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.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  Fix: Ensure `extensions=['markdown_inline_graphviz']` is used exactly as shown in your `markdown.markdown` call or `mkdocs.yml` configuration.
• breaking 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.
  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.

Install

• pip install markdown-inline-graphviz-extension Install package

Imports

• Extension String
  wrong:

  from markdown_inline_graphviz_extension import InlineGraphvizExtension

  correct:

  import markdown
  html = markdown.markdown(text, extensions=['markdown_inline_graphviz'])

  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'.

Quickstart

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.

import markdown
import os

# Ensure Graphviz 'dot' executable is in your system's PATH
# For example, on Ubuntu/Debian: sudo apt-get install graphviz
# On macOS: brew install graphviz

markdown_text = """
# My Document with a Graph

Here is a simple graph:

{% dot example.svg
digraph G {
    A -> B;
    B -> C;
    C -> A;
}
%}

Another graph using a different engine:

{% neato another.svg
node [shape=box];
A -- B;
B -- C;
C -- A;
%}

"""

# Render the markdown with the inline_graphviz extension
# Ensure the extension name is exactly 'markdown_inline_graphviz'
try:
    html_output = markdown.markdown(markdown_text, extensions=['markdown_inline_graphviz'])
    print(html_output)
except Exception as e:
    print(f"Error rendering markdown: {e}")
    print("Please ensure Graphviz is installed on your system and its executables are in your PATH.")
    print("You can test by running 'dot -V' or 'neato -V' in your terminal.")