PlantUml include does not work

[Damounet]

I am running Backstage and work with plantUML files, that I want to include in a markdown file, and it does not work.

It is working when doing an embeded plantUML graphic (first graphic) but does not work when doing an include (second graphic). The code of this documentation is available here : https://github.com/Damounet/plantuml-reproducer

My setup is as follows:

• Using a backstage application which generates the documentation with this conf in app-config.yaml:

techdocs:
  sanitizer:
    allowedIframeHosts:
      - www.youtube.com
  builder: 'local' # Alternatives - 'external'
  generator:
    runIn: 'local' # Alternatives - 'local' / default: docker
  publisher:
#    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
    type: awsS3
    awsS3:
      bucketName: ${TECHDOCS_S3_BUCKET_NAME}
      credentials:
        accessKeyId: ${TECHDOCS_S3_ACCESS_KEY_ID}
        secretAccessKey: ${TECHDOCS_S3_SECRET_ACCESS_KEY}
      endpoint: ${TECHDOCS_S3_ENDPOINT}
      region: ${TECHDOCS_S3_REGION}
      s3ForcePathStyle: true

• my MinIO has the following files: We can see that the index is generated and that the puml file is still here.

• The Dockerfile of the my Backstage App contains:

  
  FROM node:18-bookworm-slim

RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \ --mount=type=cache,target=/var/lib/apt,sharing=locked \ apt-get update && \ apt-get install -y python3 g++ build-essential python3-pip python3-venv graphviz openjdk-17-jdk ADD --chown=node:node https://github.com/plantuml/plantuml/releases/download/v1.2024.3/plantuml-1.2024.3.jar /opt/plantuml.jar RUN echo '#!/usr/bin/sh\n\njava -Djava.awt.headless=true -jar '/opt/plantuml.jar ' ${@}' > /usr/local/bin/plantuml && \ chmod +x /usr/local/bin/plantuml && \ yarn config set python /usr/bin/python3

ENV VIRTUAL_ENV=/opt/venv RUN python3 -m venv "$VIRTUAL_ENV" ENV PATH="$VIRTUAL_ENV/bin:$PATH"

RUN pip3 install mkdocs mkdocs-techdocs-core

[...]

I did found out that the plantUML Debian package is from 2020, so I installed it manually.
I truncated the end of the Dockerfile that contains all the node stuff and remains untouched from the creation of the app.

I do understand that when building docs with the techdoc container (https://github.com/backstage/techdocs-container/blob/main/Dockerfile) that there is an additional mount to do with the plantuml files, but as the files are grabbed by the techdoc plugin, and that I did not find anywhere a line of documentation on cofiguring the https://github.com/mikitex70/plantuml-markdown plugin in backstage, I do not have anything to do.
Also the Backstage documentation states that it should work right away : https://backstage.io/docs/features/techdocs/how-to-guides/#referenced-plantuml-diagram-example

Am I missing a configuration somewhere to have this working? 
Is it feasable that way (it should) ?

[pwalleni]

We run our own Kroki server and Backstage. Diagrams from external PlantUML files get included like this in a TechDocs page:

# Architecture overview

```kroki-plantuml
@from_file:diagrams/architecture_overview.puml

This is the directory structure:

```plaintext
docs/diagrams
└── architecture_overview.puml

PlantUML file contents:

@startuml Architecture Overview
!include C4_Container.puml
LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()

etc.

[Damounet]

Needs a bit of crafting but it works.

I would rather prefer a solution where the image is generated at the doc build time but this will be enough for the moment !

Thanks @pwalleni