Plugin: mkdocs-drawio¶

The mkdocs-drawio plugin allows you to embed Mondrian Diagrams directly into your MkDocs site. It renders .drawio files as interactive, zoomable diagrams and supports captions, page and layer selection. The viewer (optionally) provides the ability to create a link to the source file to edit the file.

Enable the plugin¶

The plugin is included in the Mondrian Docs build container. To make use of the plugin include the following in the mkdocs.yml file:

plugins:
  - drawio:
      background: "white"
      caption_prefix: "Figure: "
      caption_page_separator: " - "
      include_src: true
      include_page: true
      edit: true
      editor_base_url: "https://diagrams.mondrian-it.io"

Parameters¶

The parameters allow configuration of the default behaviour of the plugin in generating the viewer. These default options can be overwritten on a per diagram basis:

Parameter	Type	Description
`background`	`str`	Sets the background color of the diagram viewer. Common values: `"white"`, `"transparent"`.
`caption_prefix`	`str`	Prefix added to automatically generated captions. Example: `"Figure: "` results in `"Figure: diagram.drawio - Page 1"`
`caption_page_separator`	`str`	Separator between different caption components (e.g., source file and page).
`include_src`	`bool`	If `true`, includes the source filename (`.drawio`) in the generated caption.
`include_page`	`bool`	If `true`, includes the page name (or index) from the diagram in the caption.
`edit`	`bool`	If `true`, includes a link to open the source file in the editor specified in `editor_base_url`.
`editor_base_url`	`str`	URL of the editor used when opening the edit link in the viewer.

Use the plugin¶

Once the plugin is enabled in mkdocs.yml, you can embed .drawio diagrams directly into your Markdown pages using standard image syntax.

![](path/to/diagram.drawio)

This will render all pages of the specified .drawio file as an interactive diagram with default settings from the plugin configuration.

Parameters¶

You can control how individual diagrams are rendered using Attribute Lists, supported via the attr_list Markdown extension.

Example with attributes:

![](example.drawio){:
  data-pages="0,1"
  data-caption-prefix="Diagram: "
}

This example will only show page 0 and page 1 and use Diagram: as prefix, instead of the value provided in the plugin default configuration.

The attributes available are:

Attribute	Description
`![alt](example.drawio)`	Selects a single `page` using the `alt` text. You can use the page name or index, e.g., `![0](example.drawio)` or `![Page-0](example.drawio)`.
`data-pages`	Comma-separated list of page names or indices to render. Examples: `"0,1"`, `"Cover,Details"`, or a range like `"0-2"`. Use `@first` or `@last` for dynamic selection.
`data-layers`	Comma-separated list of layer names to show by default.
`data-caption`	Full override of the auto-generated caption. If set, it takes precedence over all other caption options.
`data-caption-prefix`	Sets a custom prefix for the caption (e.g., `"Diagram: "`). Use `"None"` to suppress the prefix entirely.
`data-caption-src`	Overrides the source label in the caption. Defaults to the `.drawio` file name. Use `"false"` or `"None"` to hide.
`data-caption-page`	Overrides the page name shown in the caption. Defaults to the actual page name. Use `"false"` or `"None"` to hide.
`data-caption-page-separator`	Defines how to separate source and page in the caption (e.g., `" - "`).
`data-edit`	Enables the edit button. Accepts `"true"`, `"false"`, or a full URL. Overrides the global `edit` setting in `mkdocs.yml`.
`data-editor-url`	Overrides the global `editor_base_url` for this specific diagram.

Examples¶

All pages¶

![](exampleDiagrams/Docs-Gitlab-Pipelines.drawio)

Figure: Docs-Gitlab-Pipelines - Index, Mondrian Toolset, Mondrian-Landscape, Broker-generated .md, Broker-Generated-Swimlane

Single Page¶

![2](exampleDiagrams/Docs-Gitlab-Pipelines.drawio)

or

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio)

or

![](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-pages="Mondrian Toolset"}

Figure: Docs-Gitlab-Pipelines - Mondrian Toolset

Layers¶

![Mondrian-Landscape](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-layers="0 2 3 4 5 6 7"}

Figure: Docs-Gitlab-Pipelines - Mondrian-Landscape

Mutiple Pages¶

![](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-pages="2,5"}

or

![](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-pages="2,@last"}

or

![](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-pages="Mondrian Toolset,Broker-Generated-Swimlane"}

Figure: Docs-Gitlab-Pipelines - Mondrian Toolset, Broker-Generated-Swimlane

Data Caption¶

No Source¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption-src=None}

Figure: None - Mondrian Toolset

Custom Source¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption-src="Example File"}

Figure: Example File - Mondrian Toolset

No Page¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption-page=None}

Figure: Docs-Gitlab-Pipelines - None

Custom Page¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption-page="The First Page"}

Figure: Docs-Gitlab-Pipelines - The First Page

No Caption¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption-src="None" data-caption-page="None"}

Figure: None - None

Custom Caption¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption="Example File & Page"}

Figure: Example File & Page

No Prefix¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption-prefix="None"}

NoneDocs-Gitlab-Pipelines - Mondrian Toolset

Custom Prefix¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption-prefix="Viewpoint: "}

Viewpoint: Docs-Gitlab-Pipelines - Mondrian Toolset

Custom Page Separator¶

![Mondrian Toolset](exampleDiagrams/Docs-Gitlab-Pipelines.drawio){data-caption-page-separator=" > "}

Figure: Docs-Gitlab-Pipelines > Mondrian Toolset

Errors¶

File is not available¶

![](file-does-not-exist.drawio)

Figure: file-does-not-exist

Page is not in file¶

![Not Existing Page](exampleDiagrams/Docs-Gitlab-Pipelines.drawio)

Figure: Docs-Gitlab-Pipelines