Add pan/zoom controls to Mermaid diagrams

[kabilar]

Issue

Currently the text in the Mermaid diagrams is quite small (example below):

Changes

• Add the mkdocs-panzoom plugin to enable panning and zooming.
• Add workflow_dispatch to trigger docs deployment manually.
• I kept the mermaid2 plugin but I don't think we need it since mkdocs material natively supports Mermaid diagrams with the markdown_extension. See reference.

Preview: https://kabilar.github.io/bican-models/anatomical_structure/

cc @satra

[gemini-code-assist]

Summary of Changes

Hello @kabilar, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the user experience for documentation viewers by introducing interactive pan and zoom capabilities for Mermaid diagrams. This change directly addresses the readability issue of small text within complex diagrams, making visual information more accessible. The implementation involves configuring the MkDocs site and updating project dependencies to support the new functionality.

Highlights

• Pan/Zoom Functionality: Integrated the mkdocs-panzoom plugin to enable interactive panning and zooming for Mermaid diagrams, addressing the issue of small text.
• Mermaid Diagram Configuration: Configured mkdocs.yml to properly render Mermaid diagrams using pymdownx.superfences markdown extension.
• Dependency Update: Added mkdocs-panzoom-plugin to the project's documentation dependencies in pyproject.toml.
• Manual Docs Deployment: Included workflow_dispatch to allow for manual triggering of documentation deployments (as per the PR description).
• Site URL Configuration: Added the site_url to mkdocs.yml for explicit site referencing.

Changelog

• mkdocs.yml
  • Added site_url to the top-level configuration.
  • Configured the panzoom plugin with full_screen, always_show_hint, and hint_location options.
  • Added markdown_extensions for pymdownx.superfences to correctly format Mermaid diagrams.
• pyproject.toml
  • Added mkdocs-panzoom-plugin to the docs dependency group.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/generate_docs.yaml

Activity

• The pull request was created by kabilar to add pan/zoom controls to mermaid diagrams.
• No further human activity (comments, reviews) has been recorded since its creation.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request effectively addresses the issue of small text in Mermaid diagrams by adding pan and zoom controls, which is a great improvement for readability. However, a critical security vulnerability was identified in the mkdocs.yml file: the pymdownx.superfences configuration allows for arbitrary code execution, posing a significant risk to the build environment. To resolve this and complete the transition to native Mermaid support, please remove the insecure pymdownx.superfences configuration and the now-redundant mkdocs-mermaid2-plugin and its associated dependency.

[gemini-code-assist]

The use of !!python/name:pymdownx.superfences.fence_code_format introduces a critical security vulnerability. This YAML tag allows for arbitrary code execution when the mkdocs.yml file is parsed. An attacker with write permissions to this file could execute arbitrary commands on the documentation build server, potentially leading to a full compromise of the build environment. It is strongly recommended to remove this configuration and use a safer method for rendering Mermaid diagrams. MkDocs Material has native support for Mermaid, which should be preferred.

[gemini-code-assist]

This plugin is a great addition for large diagrams. On a related note, as you correctly pointed out in the PR description, the mermaid2 plugin on line 13 is now redundant because you've enabled native Mermaid support via markdown_extensions. I recommend removing - mermaid2 from the plugins list to simplify the configuration.

[gemini-code-assist]

Following up on the comment in mkdocs.yml, since mkdocs-mermaid2-plugin is no longer needed, its dependency on line 30 can be removed. Please also adjust the commas in the list accordingly after removing the line to maintain valid TOML syntax.

[satra]

@kabilar - since we use the linkml generated repo for this, should this be taken upstream?

[kabilar]

@kabilar - since we use the linkml generated repo for this, should this be taken upstream?

Hi @satra, that's fair but those docs don't seem to have any large ERDs, so this extra plugin may not be needed there. I might have missed it but they all seem to be pretty small. For example: https://linkml.io/linkml-model/latest/docs/specification/03schemas/#classdefinition-uml.