MkDocs에서 PlantUML 표시

자신은 문서를 작성할 때 PlantUML을 상당히 사용합니다.
조금 오랜만에 상당한 양의 문서를 쓸 필요성이 나왔기 때문에 MkDocs로 환경 정돈하려고 생각했을 때 망설였으므로 비망록.

환경은 모두 도커 로 작성합니다.

docker로 환경 정돈하기

PlantUML Server 구축

이번 본선은 아니지만, 만약의 위립 방법을 써 둡니다.
다음을 yaml 파일을 준비하고 docker-compose up -d로 PlantUML Server를 시작합니다.

docker-compose.yaml

version: "3.7"

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

서버가 기동해 브라우저로 액세스 해, 이하와 같은 페이지가 표시되면 OK입니다.
여기서, 서버의 IP 주소는 192.168.1.100 으로 하고, 페이지는 http://192.168.1.100:18080 로 액세스 할 수 있는 것으로 해 설명을 계속합니다.

MkDocs 컨테이너 환경 만들기

MkDocs 용 컨테이너의 Dockerfile은 다음과 같습니다.
공식 파이썬 docker 이미지를 기반으로 사용하는 패키지를 추가합니다.
이번에는 MkDocs를 머티리얼 디자인 테마와 PlantUML을 사용할 수 있도록 하는 것에 머물러 있습니다.

Dockerfile

FROM python:3-buster

WORKDIR /

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

WORKDIR /docroot

그런 다음 docker-compose.yaml은 다음과 같습니다.
docroot 의 디렉토리는 mkdocs new 로 작성한 MkDocs 의 프로젝트의 디렉토리를 로컬에 보관 유지해 마운트 하도록 하고 있습니다.
컨테이너를 기동하면 mkdocs serve 로 서버가 기동하도록 하고 있습니다.
http://192.168.1.100:18000 로 이동하면 페이지가 표시됩니다.
단순히 mkdocs serve 뿐이라면 localhost:8000 에서 listen 하므로 컨테이너 밖에서 액세스 할 수 없습니다.
따라서 컨테이너 외부에서 액세스 할 수 있도록 -a 옵션을 추가했습니다.

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"

PlantUML과 협력

PlantUML과 함께 작동하려면 다음 준비가 필요합니다.

plantuml-markdown 설치

mkdocs.yml에 plantuml_markdown extension 추가

plantuml-markdown의 설치는 Dockerfile에서 이미 완료되었으므로 생략합니다.

plantuml_markdown의 확장 추가

mkdocs.yml에 다음을 추가합니다.
이전이라면, server로 설정하는 것이 htp // 192.168.1.100:18080 와 같이 마지막에 「plantuml」이 붙어 있을 필요가 있었습니다.
PlantUML Server의 사양이 바뀌었는지 이대로 움직이지 않고 자신은 망설이고 있었습니다.
그리고, 개인적으로 다이어그램은 svg 로 표시하고 싶기 때문에, 이전에는 htp // 192.168.1.100:18080 와 같이 URL에 svg 를 추가하고 있던 생각이었는데 exception 투성이로 표시되지 않고, 흠이 되어 있었습니다.

이 변도 사양이 바뀌었는지 특히 아무것도 추기할 필요는 없고, http://192.168.1.100:18080 만을 지정합니다.
주의점으로서는, 마지막 슬래시도 불필요합니다.

site_name: My Docs
theme:
  name: material

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

형식 지정이 없으면 기본 png와 같습니다.
자신처럼 기본값을 svg로 만들려면 두 가지 방법이있는 것 같습니다.

포맷을 매회 지정

디폴트의 포맷을 지정한다

형식을 매번 지정하려면 다음과 같이 "format"로 지정합니다.

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

기본적으로 지정하려면 mkdocs.yml에서 다음과 같이 지정합니다.

site_name: My Docs
theme:
  name: material

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

이상으로, 아마 현시점에서의 최신의 MkDocs 와 PlantUML 를 사용한 환경에서 문서를 작성할 수 있을까 생각합니다.
길어졌지만 여기까지 사귀어 주셔서 감사합니다.