Skip to content

Images and diagrams

MkDoxy can include existing images referenced by Doxygen comments in generated API pages. Doxygen can also draw graphs from code or text definitions. These are two separate workflows with different tool requirements.

Open the image and diagram gallery on this site to see all seven image inputs and ten native Doxygen diagram examples. The generated ImageExample API shows images copied by MkDoxy during this documentation build.

Support and required tools

Task Tools to install Where it works
Copy existing SVG, PNG, JPG/JPEG, GIF, BMP or WebP images referenced by @image html Python with MkDoxy/MkDocs, plus the Doxygen executable MkDoxy full API documentation
Generate inheritance, collaboration, include, call or caller graphs Doxygen and Graphviz (dot) Native Doxygen output; automatic MkDoxy rendering is not implemented
Render @dot or @dotfile definitions Doxygen and Graphviz (dot) Native Doxygen output
Render @msc or @mscfile sequence charts Doxygen with built-in mscgen, as in the tested Doxygen 1.15.0 Native Doxygen output
Build the combined repository gallery The locked development environment, Doxygen and Graphviz Local Material for MkDocs gallery
Regenerate the repository's raster input fixtures Pillow 12.1.1 Optional maintainer task; not needed to build or test the existing inputs

Graphviz and Pillow are not required to copy an existing image through MkDoxy. Python packages do not install the system Doxygen or Graphviz executables.

On Debian/Ubuntu, install Doxygen; add Graphviz when generating diagrams:

sudo apt update
sudo apt install doxygen
sudo apt install graphviz  # Optional for existing images; needed for graph examples.

For other systems, use the Doxygen downloads and Graphviz installation instructions. Make their executables available on PATH, then verify:

doxygen --version
dot -V  # Only needed for Graphviz-based diagrams.

The plugin's Python requirement is declared in pyproject.toml (currently Python 3.10 or newer). Install MkDoxy in your Python environment; a source checkout can use the setup in the contributing guide. The examples on this page describe the image-copy support in the source tree; an older installed package release may not include it yet.

Include an existing image

For this layout:

my-project/
├── mkdocs.yml
├── docs/
│   └── index.md
├── src/
│   └── image_example.h
└── images/
    └── pipeline.svg

Reference the image in src/image_example.h:

/**
 * Build documentation from source code.
 *
 * @image html pipeline.svg
 */
class ImageExample {
public:
    /** Generate the API documentation. */
    void build();
};

Configure Doxygen's image search path in mkdocs.yml:

site_name: My documentation
plugins:
  - mkdoxy:
      projects:
        api:
          src-dirs: src
          full-doc: true
          doxy-cfg:
            FILE_PATTERNS: '*.h *.cpp'
            IMAGE_PATH: images
            EXAMPLE_PATH: ''
            EXTRACT_ALL: true
            GENERATE_HTML: false
            GENERATE_LATEX: false
      full-doc: true
markdown_extensions:
  - tables

Run mkdocs build from my-project/. Paths such as src and images in this example are relative to that working directory.

Doxygen copies the image into its XML output. MkDoxy copies it alongside the generated API Markdown and registers it with MkDocs. MkDocs then produces the HTML page and the image asset in the site directory. No separate copy step is needed for this full-documentation workflow.

The resulting API page displays this diagram:

Example image referenced by a Doxygen comment

The supported extensions are .svg, .png, .jpg, .jpeg, .gif, .bmp and .webp, matched without regard to extension case. JPG and JPEG share one encoding. Animated GIF files retain their input bytes. Rendering still depends on the browser's support for the chosen format.

Image files are published unchanged. Include only assets trusted to run on your documentation origin: SVG may contain active content when opened directly. MkDoxy does not sanitize SVG or other authored documentation. See the security policy for the trusted-build-input model.

The current image renderer emits a Markdown image with the alt text Image. Doxygen caption and size options are not currently forwarded to that Markdown. Automatic asset copying requires full documentation to be enabled at both the plugin and project level; a snippet-only project does not run this copy step.

Custom output paths and rebuilding

A project can set api-path: reference/cpp and the plugin can set save-api: build/doxygen to retain its generated files. Image assets follow the selected API path. Both directory URLs and use_directory_urls: false are covered by the image integration tests.

When retaining Doxygen output with save-api, mkdocs build --clean cleans the site directory but does not remove that separate saved cache. The cache tracks source files, the project configuration passed to Doxygen and files under IMAGE_PATH, including image inputs outside src-dirs. A failed or interrupted generation does not leave a valid cache hash; the next build retries it.

Different assets cannot share one output path: MkDoxy stops the build if a generated image conflicts with an existing documentation asset. An identical file already present in docs/ is reused. Remove an obsolete manually copied asset or rename it to resolve a conflict. Copy failures also stop the build; they are not silently omitted. Only image references from the current indexed XML compounds are registered; stale images left in a retained output directory are not republished. An API path that would overwrite a different current XML image input is rejected before copying; use a separate output path to resolve that ambiguity. Generated cache/API paths must not overlap docs_dir, so a build cannot replace a hand-authored documentation source through its image-copy step. Symlinks that already resolve outside the XML source directory or API destination are rejected. Remote and site-root image URLs (such as /media/example.svg) remain unchanged; MkDoxy does not read or copy them from the host filesystem. The site must provide their targets separately. Relative asset paths that escape the XML directory are rejected. Build in a workspace writable only by trusted processes; these path checks do not provide isolation against concurrent filesystem changes.

If an image is missing, check the filename and its case, IMAGE_PATH, the Doxygen diagnostics, the generated XML image reference, and the final HTML image URL. A successful build alone does not prove that an image URL works.

Generate diagrams with native Doxygen

Doxygen and Graphviz can derive diagrams from C++ structure. For example, demo-projects/diagrams/model.h declares a builder with a base class and two member types. The following illustrations are generated from that example.

These are native Doxygen outputs embedded as documentation illustrations. MkDoxy does not currently turn these graph elements in Doxygen XML into Markdown diagrams. Setting HAVE_DOT alone does not add them to a MkDoxy page. You can publish native Doxygen HTML separately or generate a static image and include it through the existing-image workflow above.

Diagram Input Doxygen uses Example output
Inheritance C++ base classes Native Doxygen inheritance graph
Collaboration C++ member types and inheritance Native Doxygen collaboration graph
Calls Function calls in C++ implementations Native Doxygen call graph

The example Doxyfile enables graph generation:

GENERATE_HTML = YES
GENERATE_XML = YES
HAVE_DOT = YES
DOT_IMAGE_FORMAT = svg
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
SOURCE_BROWSER = YES

The Doxygen graph manual describes these graph types and their configuration. The repository gallery generates both SVG and PNG versions.

Explicit graph definitions

An inline Graphviz graph can be placed inside a Doxygen comment:

/**
 * @dot
 * digraph Build {
 *   rankdir=LR;
 *   Source -> XML -> Markdown -> HTML;
 * }
 * @enddot
 */

Alternatively, @dotfile states.dot reads a separate Graphviz definition. DOTFILE_DIRS tells Doxygen where to find that input.

Sequence charts can use Doxygen's built-in mscgen:

/**
 * @msc
 * client,worker,cache;
 * client=>worker [label="build()"];
 * worker=>cache [label="lookup(source hash)"];
 * cache>>worker [label="miss"];
 * worker>>client [label="HTML + assets"];
 * @endmsc
 */

Native Doxygen sequence chart

@mscfile exchange.msc reads a separate sequence definition, configured through MSCFILE_DIRS. These commands are demonstrated in demo-projects/diagrams/.

Additional optional tools

Doxygen also supports PlantUML diagrams through a Java runtime and a PlantUML JAR, and Dia diagrams through the Dia executable. These tools are separate installations and were not used to generate the repository gallery. Some PlantUML diagram types also need Graphviz. Mermaid commands and rendering modes depend on the installed Doxygen version. Consult the matching Doxygen command reference before using these optional integrations.

From a repository checkout, install Doxygen and Graphviz, then run:

uv sync --locked --extra dev
uv run --locked --extra dev python demo-projects/diagrams/build_gallery.py

The command prints the path to a newly generated site directory. It contains seven image inputs displayed through MkDoxy, ten native Doxygen graph examples, SVG and PNG graph variants, and expandable views of the actual source files. To inspect it in a browser, serve the printed directory, replacing the path:

python -m http.server 8000 --directory /path/printed/by/the/command/site

Normal gallery builds need no Pillow: the raster inputs are stored in the repository. Only regenerating those inputs requires it:

uv run --locked --extra dev --with pillow==12.1.1 python tests/integration/fixtures/image_assets/generate_assets.py

This changes fixture files. Review the resulting images and rerun the tests; do not automatically accept a regenerated output as correct. The seven-format fixture is in tests/integration/fixtures/image_assets/.

To refresh the static native-diagram illustrations used on this site explicitly:

uv run --locked --extra dev python demo-projects/diagrams/build_gallery.py --export-docs-assets

This updates docs/media/diagrams/. Review the SVG differences: layout can vary with Doxygen, Graphviz and font versions. Ordinary documentation builds consume these stored illustrations and do not require Graphviz. The gallery examples were generated with Doxygen 1.15.0 and Graphviz 14.1.2.