MkDocs PanZoom Plugin

0.5.2 · active · verified Sat Apr 11

The MkDocs PanZoom Plugin is an active MkDocs plugin, currently at version 0.5.2, designed to add pan and zoom functionality to images and Mermaid/D2 diagrams within your MkDocs generated documentation. It enhances user interaction with visual content by allowing navigation and magnification, and it maintains a steady release cadence with recent updates improving performance and features.

Warnings

breaking As of version 0.4.0, the plugin requires explicit configuration of `pymdownx.superfences` for Mermaid/D2 diagrams to work, and the `site_url` must be defined in `mkdocs.yml`. Additionally, the `exclude` (pages) configuration option was removed.
Fix: Add `markdown_extensions` for `pymdownx.superfences` as shown in the quickstart, ensure `site_url` is set, and use the `pz-ignore` class for individual exclusions instead of `exclude` pages option.
gotcha The `site_url` parameter in `mkdocs.yml` must be defined for the plugin to function correctly, particularly with diagram and image handling.
Fix: Ensure `site_url: https://your-domain.com/your-docs/` is present and correctly configured in your `mkdocs.yml`.
gotcha The `exclude_selectors` option in the plugin configuration is intended only to disable the *default* selectors (e.g., '.mermaid', '.d2'). To exclude a *specific item* (image or diagram) from pan/zoom, you must add the CSS class `pz-ignore` to that item in your Markdown.
Fix: For specific item exclusion, apply the `pz-ignore` class directly to the HTML element or Markdown that generates it. E.g., `![Alt text](image.png){.pz-ignore}`.

Install

pip install mkdocs-panzoom-plugin Install package

Quickstart

To activate the plugin, add `panzoom` to your `plugins` list in `mkdocs.yml`. For Mermaid and D2 diagrams to work correctly with pan/zoom since version 0.4.0, you must also configure `pymdownx.superfences` under `markdown_extensions` and define your `site_url`. The example demonstrates enabling pan/zoom for images, showing the hint permanently, setting an initial zoom, and configuring `pymdownx.superfences`.

plugins:
  - search
  - panzoom:
      # Enable pan/zoom for images
      include_selectors:
        - "img"
      # Optional: always show the hint (default: false)
      always_show_hint: true
      # Optional: set initial zoom level (default: 1.0)
      initial_zoom_level: 1.2
      # Optional: enable fullscreen (still in development)
      full_screen: False

# Required for Mermaid/D2 diagrams with panzoom since v0.4.0
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

site_url: https://example.com/your-docs/

view raw JSON →