Not working with backstage tech docs #16
Description
📜 Description
I am unable to render a Draw.io diagram inside Backstage TechDocs. The diagram renders correctly when using npx @techdocs/cli serve, but fails to display when using yarn dev in the Backstage instance. I have set up the correct MkDocs Docker image with all necessary plugins, but the diagram doesn't show up in Backstage.
👍 Expected behavior
The .drawio diagram should render in the Backstage TechDocs instance just like it does when running npx @techdocs/cli serve.
👎 Actual Behavior with Screenshots
The .drawio diagram does not render in the Backstage instance when I use yarn dev to run Backstage. The diagram works correctly in npx @techdocs/cli serve, but fails in the Backstage environment.
👟 Reproduction steps
I am using the mkdocs-drawio plugin to render Draw.io diagrams, and I have included the external viewer JS (https://viewer.diagrams.net/js/viewer-static.min.js) in the configuration.
It works locally when serving with npx @techdocs/cli serve, but fails to render in the Backstage TechDocs.
Dockerfile for TechDocs Image: I have created a custom Docker image with the following Dockerfile:
Bug Report: Draw.io Diagram Not Rendering in Backstage TechDocs
Summary:
I am unable to render a Draw.io diagram inside Backstage TechDocs. The diagram renders correctly when using npx @techdocs/cli serve, but fails to display when using yarn dev in the Backstage instance. I have set up the correct MkDocs Docker image with all necessary plugins, but the diagram doesn't show up in Backstage.
Steps to Reproduce:
Dockerfile for TechDocs Image:
I have created a custom Docker image with the following Dockerfile:
FROM python:3.10-alpine
RUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfig
RUN apk --no-cache add git
# Download plantuml file, validate checksum, and move to the correct location
RUN curl -o plantuml.jar -L https://github.com/plantuml/plantuml/releases/download/v1.2024.6/plantuml-1.2024.6.jar && echo "3e944755cbed59e1ed9332691d92294bef7bbcda plantuml.jar" | sha1sum -c - && mv plantuml.jar /opt/plantuml.jar
RUN pip install --upgrade pip && pip install mkdocs-techdocs-core
RUN pip install mkdocs-macros-plugin
RUN pip3 install mkdocs-build-plantuml-plugin
RUN pip install mkdocs-inline-select-svg-plugin
RUN pip install mkdocs-drawio
ENV diagramDir=docs/diagrams
RUN echo $'#!/bin/sh\n\njava -Dplantuml.include.path=${diagramDir} -jar /opt/plantuml.jar ${@}' > /usr/local/bin/plantuml
RUN chmod 755 /usr/local/bin/plantuml
ENTRYPOINT [ "mkdocs" ]2 MkDocs Configuration (mkdocs.yml):
My mkdocs.yml is configured with the required plugins, including the mkdocs-drawio plugin and the external viewer JS:
site_description: An informative description
plugins:
- macros
- inline-select-svg
- techdocs-core
- drawio:
viewer_js: 'https://viewer.diagrams.net/js/viewer-static.min.js'
nav:
- Getting Started: index.md
extra:
unit_price: 103 Running Locally via npx @techdocs/cli serve:
When I run below command
npx @techdocs/cli serve --docker-image mkdocs:drawio
The diagram renders perfectly at http://localhost:8000
Backstage Configuration:
In the Backstage instance, I have created a Component entity for my documentation as follows:
catalogue.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: draw-io-doc
title: draw-io-doc
annotations:
backstage.io/techdocs-ref: dir:./draw-io-doc
spec:
type: documentation
lifecycle: pre-production
owner: architectsWhen I run below command in backstage home
yarn dev
Open below url
http://localhost:3000/docs/default/component/draw-io-doc
Resulting draw-io diagram disappearing
📃 Provide the context for the Bug.
Showing drawio diagram in techdocs
🖥️ Your Environment
mac os
👀 Have you spent some time to check if this bug has been raised before?
I checked and didn't find similar issue
Are you willing to submit PR?
Yes I am willing to submit a PR!