RFC: Automatic transforms to catalog entities in mermaid

[jtreher]

I had an idea, but I don't know if it would actually be practical in the long term. This would make sense for diagrams where you are showing detail for how systems interact with one another. Like, I want to create very specific graphs for specific use cases of our enterprise.

I am looking for comment regarding a token you could add to your diagram nodes to indicate that they are catalog entities (ex: *** as a prefix for an entity to be followed by its entity ref (partial?))

1. If that token is found in the diagram, before doing the render of the mermaid string, it would fetch the entity details for the indicated entities found from the catalog API.
2. It would replace the text from the marker to the entity title and it would also make the diagram node a clickable link

For example:

graph
    ***system/my-system-->***system/another-system

would be converted to

graph
    my-system[My system]-->another-system[Another System]

    click my-system "/catalog/default/system/my-system" _blank
    click another-system "/catalog/default/system/another-system" _blank

Cons:

1) Mermaid preview works really well in markdown preview tools with the right extensions. This would make a real preview only possible in Backstage or with the TechDocs CLI. 2) Potential security issue unless you only allow relative links . 3) More complexity in the plugin.

[johanneswuerbach]

I think this idea sounds really interesting.

Mermaid preview works really well in markdown preview tools with the right extensions. This would make a real preview only possible in Backstage or with the TechDocs CLI.

This could probably be mitigated by making un-process diagrams also valid diagrams and have the processing only enhance them.

E.g. use

flowchart LR
    my-system["bs:system/my-system"]
    another-system["bs:system/another-system"]
    my-system --> another-system

which is translated

flowchart LR
    my-system
    another-system
    click my-system "/catalog/default/system/my-system" _blank
    click another-system "/catalog/default/system/another-system" _blank
    my-system --> another-system

So the diagram, would be still usable before and after. Another option could be to have this information in comments.

allow relative links

I think allowing only relative resolution might be a good start.

[jtreher]

I wonder if the new PresentationAPI https://backstage.io/docs/releases/v1.20.0#catalog-presentation-api could be leveraged to make the replacements super fast.