Display PlantUML in MkDocs

I use PlantUML quite a bit when writing documentation. It's been a while since I needed to write a good amount of documents, so I stumbled when I thought about setting up the environment with MkDocs, so I made a memorandum.

All environments are created with docker.

Prepare the environment with docker

Build PlantUML Server

It's not the main point of this time, but I will write how to make it just in case. Prepare the following yaml file and start PlantUML Server with docker-compose up -d.

docker-compose.yaml

version: "3.7"

services:
  plantuml:
    image: plantuml/plantuml-server
    ports:
      - 18080:8080

It is OK if the server starts and you access it with a browser and the following page is displayed. Here, the IP address of the server is * 192.168.1.100 *, and the page can be accessed at http://192.168.1.100:18080, and the explanation is continued.

Create a container environment for MkDocs

The Dockerfile of the container for MkDocs is as follows. Add a package that is based on the official python docker image. This time around, we're just making MkDocs available for Material Design themes and PlantUML.

Dockerfile

FROM python:3-buster

WORKDIR /

RUN pip install -U \
        pip \
        mkdocs \
        mkdocs-material \
        plantuml-markdown \
    && mkdocs new docroot

WORKDIR /docroot

Next, docker-compose.yaml looks like this: As for the docroot directory, the directory of the MkDocs project created with * mkdocs new * is kept locally and mounted. When I start the container, * mkdocs serve * starts the server. If you access http://192.168.1.100:18000, the page will be displayed. If you simply use mkdocs serve, it will listen on localhost: 8000, so you cannot access it from outside the container. Therefore, we have added the -a option so that it can be accessed from outside the container.

docker-compose.yaml

version: "3.7"

services:
  mkdocs:
    build:
      context: ./
      dockerfile: ./Dockerfile
    volumes:
      - ./docroot:/docroot
    ports:
      - 18000:8000
    tty: true
    command: bash -c "mkdocs serve -a 0.0.0.0:8000"

Works with PlantUML

The following preparations are required to link with PlantUML.

--Install plantuml-markdown --Added plantuml_markdown extension to mkdocs.yml

I will omit the installation of plantuml-markdown because it is already done with Dockerfile.

Addition of plantuml_markdown extension

Add the following to mkdocs.yml: Previously, the server had to be set to http://192.168.1.100:18080/plantuml with "plantuml" at the end. I was stumbling because it didn't work as it was because the specifications of PlantUML Server changed. Also, I personally want to display the diagram as svg, so I felt like I had added svg to the URL like http://192.168.1.100:18080/plantuml/svg/, but it is displayed full of exceptions. It was hmm.

There is no need to add anything in this area as to whether the specifications have changed, and only http://192.168.1.100:18080 is specified. Note that you don't even need the last slash.

site_name: My Docs
theme:
  name: material

+ markdown_extensions:
+  - plantuml_markdown:
+      server: http://192.168.1.100:18080

If no format is specified, it looks like the default png. If you want to default to svg like yourself, there seem to be two ways.

--Specify the format every time --Specify the default format

To specify the format each time, specify "format" as shown below.

    ```plantuml format="svg"
    @startuml
    Bob -> Alice : hello
    @enduml
    ```

To specify by default, specify as follows in mkdocs.yml.

site_name: My Docs
theme:
  name: material

markdown_extensions:
 - plantuml_markdown:
     server: http://192.168.1.100:18080
+    format: svg

With that, you can probably create a document in the environment using the latest MkDocs and PlantUML at the moment. It's been a long time, but thank you for staying with us so far.