`Priority` property explanation, plantuml is not rendered with priority=23 and the latest mkdocs

[artemptushkin]

Please elaborate on the property priority in the documentation to be able to troubleshoot around it, right now there is nothing to use to understand what's going on

My stack is:

• mkdocs, version 1.3.0
  • monorepo plugin
  • search plugin
  • material theme
  • plantuml markdown extension (this)

I had

• priority: 100
• a plain *.md file with a plain plantuml inside it:

""" plantuml == I'm embedded plantuml == actor -> another_actor """

And it has never been rendered until I decided to tweak the magic priority, instance switch to 100 helped and I don't know why

[bharatrajagopalan]

@artemptushkin

I ran into this same issue with the latest released plugin

Interestingly I was able to fix this surprisingly by indenting the code block without increasing priority

 _```plantuml
A->B: Works!
_```

where the _ above represents a single space.

I can also see that in the development branch , priority has been bumped up to 30 and this now works,

when I tried debugging the plugin, , I realised that the priority was controlling how mkdocs actually fed content to the plugin itself i.e. when priority was 23 the entire code block was ignored as part of the initial input sent to the the plantuml_markdown.py file (unless indented - which was weird), and if priority was increased then it came through.

So my guess is priority is something that markdown_py/mkdocs uses to decide the order in which it will process the plugins ;I am guessing that when you have multiple plugins, some may override the other, and hence there needs to be a sequence in which these plugins are applied in the markdown file.

By increasing the priority , we seem to be overriding this sequence.

e.g. maybe the code block rendering process in markdown is intercepting the code block before the plantuml-markdown plugin is picking up the same block and hence increasing the priority ensures that plantuml-markdown gets first dibs at code blocks with the plantuml tag before the code block rendering process in markdown picks it up

[artemptushkin]

@bharatrajagopalan thanks for the explanation, I believe it's good for history.

Let's keep the issue open then till the next release, I'll try to delegate to a new default value and we close if it's as expected

Feel free to tag me to verify when it's ready

[bharatrajagopalan]

Feel free to tag me to verify when it's ready

@artemptushkin you can give it a try with this pull request

https://github.com/mikitex70/plantuml-markdown/pull/65

you just need to manually replace the plantuml_markdown.py with the one from the pull request to check, it has to be loaded into the 'python/site-packages` folder

in my mkdocs_material docker container - the file is present in /usr/local/lib/python3.9/site-packages/plantuml_markdown.py, it may differ for you.

---

Just FYI, the way I tested it on mkdocs material is as follows

create a folder called python in the your workspace (in the same folder as mkdocs.yml) and put the plantuml_markdown.py in the python folder

use the following docker files to test (the docker-compose file has a volume mapping to override the file in the container with the file from the pull request

Dockerfile

FROM squidfunk/mkdocs-material
RUN \
    pip install --upgrade pip && \
    pip install \
        plantuml-markdown  \
        mkdocs-plugin-inline-svg 

docker-compose.yml

version: '3.3'

services:
  mkdocs-material:
    build:
      context: .
      dockerfile: Dockerfile
    image: squidfunk/mkdocs-material
    container_name: mkdocs-material
    ports:
      - 8000:8000
    volumes:
      - .:/docs
      - ./python/plantuml_markdown.py:/usr/local/lib/python3.9/site-packages/plantuml_markdown.py 
    stdin_open: true
    tty: true
    privileged: true

in my mkdocs.yml,

• I didn't have to update too much of the plantuml-markdown config - you can see priority is commented out since it defaults to 30 now.
• I am using plantuml server for rendering as it is faster
• Change the base_dir path appropriately to where your plantuml diagrams are for the !include statement. note the /docs/docs - in the container, the workspace directory is /docs (where the mkdocs.yml will be located) and hence this appears twice.

markdown_extensions:
  - plantuml_markdown:
      server:  https://www.plantuml.com/plantuml          # PlantUML server, for remote rendering
      cachedir:  /tmp                                     # set a non-empty value to enable caching
      base_dir: /docs/docs/plantuml/include               # where to search for diagrams to include
      format:  'svg_inline'                               # default diagram image format
      classes: 'plantuml'                                 # default diagram classes
      title:   'UML diagram'                              # default title (tooltip) for diagram images
      alt:     'UML diagram image'                        # default `alt` attribute for diagram images
      # priority: 30                                       # plugin priority; the higher, the sooner will be applied (default 30)
      # http_method: GET                                   # GET or POST  - note that plantuml.com only supports GET (default GET)       
      # fallback_to_get: True                              # When using POST, should GET be used as fallback (POST will fail if @startuml/@enduml tags not used), (default True)
      # theme: bluegray                                    # theme to be set, can be overriden inside puml files, (default none)
      # puml_notheme_cmdlist: [                             
      #                         'version', 
      #                         'listfonts', 
      #                         'stdlib', 
      #                         'license'
      #                       ]                             # theme will not be set if listed commands present (default as listed)

then

docker-compose build

and

docker-compose up

[mikitex70]

Give me some time, lately I don't have much free time. As soon as I can I read calmly and let you know.

[mikitex70]

Ok, I'm here. I've added in the README.md (in the develop branch at this time) an explanation of what is the priority plugin configuration. @artemptushkin, I don't know why you needed to set priority: 100 to get the diagram rendered but your example code was wrong. You wrote:

"""
plantuml
== I'm embedded plantuml ==
actor -> another_actor
"""

instead of:

"""plantuml
== I'm embedded plantuml ==
actor -> another_actor
"""

so the plugin was unable to discover that the fenced code needs to be processed. Usually the priority does not need to be changed, raising does not render the diagram faster, it will only let him to be executed before other plugins can "touch" the text.

[artemptushkin]

@mikitex70 thanks I reviewed the docs it's fine

I think I copy-pasted wrongly, it was """plantuml for me when I found the issue

Let's close with the applied doc, it's sufficient