mkdocs_puml

mkdocs_puml copied to clipboard

Is your feature request related to a problem? Please describe. Looking for configuration to provide width and height for the generated images.

Describe the solution you'd like along with uml, provide option to width and height

Describe alternatives you've considered Similar one is here https://github.com/mikitex70/plantuml-markdown#introduction

Additional context we do have large sequence diagrams which cant be renedered in mkdocs with existing size. if you can provide size and height, it would be great help.

tried https://github.com/blueswen/mkdocs-glightbox#usage. it works for existing images, but not for generated images

Hi @ravikumar2026, thanks for this suggestion. Currently diagrams are stored as simple <svg> tags in html page. Interesting if it's possible to keep them in an interractive block (similar to what GitHub does with Mermaid diagrams) 🤔 . As a workaraund you could zoom a whole page

thank @MikhailKravets for the replay.

so, if it svg in a html page, do we you why glightbox doesn't work ? because, there are some existing images working with this extention.

second question, can i mention something like this

<p>
        <img width = {700px} />
       ```plantuml
       ``` 
    </a>
    
</p>

Something like this would be nice SVG pan & zoom

let me try with this

I use the mkdocs_build_plantuml project for that functionality since it replaces it with an image file so lightbox doesn't have an issue dealing with it.

I'm interested in implementing this functionality, I have the same use-case requiring glightbox for larger sequence diagrams.

@ravikumar2026 - I assume you've tried a bunch of things already, have you found a container for svg that would allow you to integrate with lightbox? Would save me from starting from 0, thanks :)

I looked into this some more and got a hacky version working but it's not pretty. I've decided it's not worth the effort and increased complexity to support.

It includes one too many changes I would rather @MikhailKravets look into first, I highlighted them in the notes below.

I'm going to look into integrating svg-pan-zoom, it might be the better option.

Here's the details of my attempts in case someone comes looking for it.

---

Attempt 1

I initially thought it was failing due to the type of image (inline svg) and not an actual image, I thought it would be as simple as

• Encode the inline svg output from plantuml as base64
• Use the b64 source and an image tag

Insight

Well i tried that and it didn't work, I dug into glightbox behavior to understand what's happening. Glightbox (GL) searches for image tags and wraps them with a GL div during the on_content mkdocs event.

This is a problem because the on_content event triggers before the on_post_page, and the on_post_page is where mkdocs_puml does the replacement of the uuid pre element.

Had they been using the same event we could have worked this out either by ordering GL first in the plugin list or using the priorities decorators, but unfortunately that's not an option.

When GL runs, there are no image tags for it to match. Fair enough, lets try to make an image tag.

Attempt 2

To resolve the ordering issue I set out to change the on_page_markdown logic in mkdocs_puml to replace the <pre> element with an img element, something like

Note This is one of the changes that would need reviewed, i'm not sure why the <pre> tag was chosen, and if there's some functionality that would break if it's replaced.

f'<img class="{self.pre_class_name}" src="data:image/svg+xml;base64,{id_}" />'

The idea was that we'll have an image tag for GL to match against.

After much mucking around I got it to work but that didn't actually fix anything.

Insight

GL wraps the message but also references the img content for the href like this

<a class="glightbox" href="data:image/svg+xml;base64,PUML_UUID" 
   data-type="image" data-width="auto" data-height="auto" data-desc-position="bottom"> 
  <img src="data:image/svg+xml;base64,xxxBASE64xxx">
</a>

Have you spotted the issue? GL picks up the UUID and not the actual image b64 since it ran first.

So to fix this we'd need to also handle updating GL's references after it runs to ensure the UUID gets replaced.

Attempt 3

Using the event order we know that we get the page after GL has done its initial process in on_page_content when we fire the on_post_page and match both the GL stuff and our own to replace uuid with image.

Finally after a long road it's in a state that should work, looking like this

Note: This change would require scanning the doc twice, once for our matches and once for GL matches. This seemed way out of scope for the plugin.

<a class="glightbox" href="data:image/svg+xml;xxxxBASE64,xxxxxx" 
   data-type="image" data-width="auto" data-height="auto" data-desc-position="bottom"> 
  <img src="data:image/svg+xml;base64,xxxxBASE64xxxx">
</a>

Success? Seems like it, but now our light vs dark stuff is broken.

Insight

So now i dug into GL again, and it's a matter of simply calling lightbox.reload from javascript after we switch out the pictures, once we have that we're good to go.

One other thing to take care of is GL's usage of a fixed background, for this thankfully there was an option flag

- glightbox: # enable lightbox for images
      background: var(--md-default-bg-color)

This will be available in version 2.0.0. As for now you may install rc version

pip install mkdocs_puml==2.0.0rc3

Read more in release notes https://github.com/MikhailKravets/mkdocs_puml/releases/tag/v2.0.0rc2

The support of pan and zoom was added in version 2.0.0