mkdocs-puml-mod 0.0.1

Package that brings PlantUML to MkDocs

This repo is a fork of https://github.com/MikhailKravets/mkdocs_puml

mkdocs_puml is a fast and simple package that brings plantuml diagrams to MkDocs documentation. mkdocs-puml-mod will allow you to use plantuml diagrams when superfences is being used.

Install

Run the following command to install the package

pip install mkdocs-puml-mod

How to use

Just add plantuml plugin into plugins section of your mkdocs.yml file, in order to use puml with mkdocs.

plugins:
    - plantuml:
        puml_url: https://www.plantuml.com/plantuml/

plantuml plugin uses PlantUML only as an HTTP service. So, you should necessarily specify puml_url config.

The plantuml config with the full list of parameters is below

plugins:
    - plantuml:
        puml_url: https://www.plantuml.com/plantuml/
        num_workers: 8
        puml_keyword: puml

Where

Parmeter	Type	Descripton
puml_url	str. Required	URL to the plantuml service
num_workers	int. Default 8	Max amount of concurrent workers that request plantuml service
puml_keyword	str. Default puml	The keyword for PlantUML code fence, i.e. ```puml ```

Now, you can put your puml diagrams into your .md documentation. For example,

## PUML Diagram

```puml
@startuml
Bob -> Alice : hello
@enduml
```

At the build step mkdocs sends requests to puml_url and substitutes your diagram with the svg images from the responses.

Run PlantUML service with Docker

It is possible to run plantuml/plantuml-server as a Docker container.

Add a new service to the docker-compose.yml file

version: "3"
services:
  puml:
    image: plantuml/plantuml-server
    ports:
      - '8080:8080'

Then substitute puml_url config with the local URL in the mkdocs.yml file

plugins:
    - plantuml:
        puml_url: http://127.0.0.1:8080
        num_workers: 8

Obviously, this approach works faster than using remote plantuml.com.

Standalone usage

You can use PlantUML converter without mkdocs. Below is the example,

from mkdocs_puml_mod.puml import PlantUML

puml_url = "https://www.plantuml.com/plantuml"

diagram1 = """
@startuml
Bob -> Alice : hello
@enduml
"""

diagram2 = """
@startuml
Jon -> Sansa : hello
@enduml
"""

puml = PlantUML(puml_url, num_worker=2)
svg_for_diag1, svg_for_diag2 = puml.translate([diagram1, diagram2])

How it works

The package uses PlantUML as an HTTP service. It sends GET requests to PlantUML service and receives svg images representing the diagrams.

The plantuml plugin parses .md documentation files and looks for

```puml

```

code blocks. When puml code block is found it is saved to the buffer for a later request to PlantUML service. In this step, we replace puml block with the uuid.

NOTE you must set puml keyword as an indicator that the PlantUML diagram is located in the block. Default keyword can be changed for the custom one in mkdocs.yml config file by using puml_keyword parameter.

After all pages are parsed, plantuml plugin requests PlantUML service with the collected diagrams. After the responses are received, the package substitutes uuid codes in markdown files with the corresponding svg images.

Acknowledgements

Have combined code from 2 repos. Credits:

1. pugong, Fralau https://github.com/fralau/mkdocs-mermaid2-plugin
2. Mikhail Kravets https://github.com/MikhailKravets/mkdocs_puml

Allows the plugin to work when using pymdownx.superfences with snippets enabled. Have moved all the event handling code to post_page event so that pymdownx.snippets can work on puml snippets inside the fences.

If using superfences, you will need to add the below lines in superfences config in mkdocs.yml

markdown_extensions:
  - pymdownx.superfences:          #pymdown-extensions installed
      custom_fences:
        - name: puml
          class: puml
          format: !!python/name:mkdocs_puml_mod.fence.fence_puml

License

The project is licensed under MIT license.