Docfx: Support for PlantUML in Markdown

[dbeuchler]

DocFX Version Used: 2.29.1
Template used: default (default or statictoc or contain custom template)

In GitLab it is possible to add PlantUML Code to markdown files with:

```plantuml
Bob -> Alice : hello
Alice -> Bob : Go Away
```

The result looks as in the following image:

For us it would be a big benefit to remove all our commited binaries (jpgs exported from Enterprise Architect) in our repositories.

For docfx it would mean that it needs some kind of pre processor which posts the data to a public or self hosted PlantUML Server, save the image to a defined folder and replace markdown code with the resulting image.

Gitlab posts the image to the PlantUML Server and uses the image link in the markdown file which is not a good option for offline documentation.

Is some kind of feature planned or what would be the best way to implement it?

[vwxyzh]

1. PlantUML Server is required.
2. Markdown code render should be overwritten.

[vicancy]

I would say a pure frontend solution, e.g. https://mermaidjs.github.io/ is more acceptable. @dbeuchler do you think https://mermaidjs.github.io/ is a good way to go?

[dbeuchler]

A pure frontend solution (but "offline") is acceptable but currently mermaidjs dos not support several diagram types. In our application we have a lot of StateMachine and Component Diagrams which are currently not supported but as far as I see, these diagram types can be covered by generic squares, circles and arrows.

[shadow-cs]

PlantUML server is not generally required since PlantUML may be executed as standalone app (via Java) and supplied externally as an argument. It also requires graphviz to be installed and visible though the search path.

PlantUML does support SVG output which is ideal for web presentation (GitLab uses PNGs which offer better compatibility but worse visuals).

Recently I enjoyed using vscode-markdown-preview-enhanced for writing documentation, it would be great if some of its features were integrated to docfx (diagramming being the primary one ;-)).

[KevReed]

I just created https://github.com/KevReed/DocFx.Plugins.PlantUml, hopefully this will be useful

[superyyrrzz]

@KevReed Looks great. Can you add your plugin to dashboard? https://github.com/dotnet/docfx/blob/dev/Documentation/templates-and-plugins/templates-dashboard.yml

[cjlotz]

Would be great to have this supported in V3 as well

[hollowdrutt]

Extend Markdown/Wiki to support mermaid & plantuml plugins, enabling UML sequence, class, flowchart diagrams has been added to the roadmap for Azure Devops Wiki.

If that gets implemented and if docfx gets support for Markdown as output then it would be possible to use docfx to build documentation including diagrams, code snippets etc and generate markdown output to be published in Azure Devops Wiki

[hollowdrutt]

Mermaid diagram support in Azure Devops Wiki is rolling out.
Azure Devops Wiki will not get support for PlantUML at this time

[cilerler]

I don't think Mermaid can match up with PlantUML, please use your votes here https://developercommunity.visualstudio.com/idea/747577/add-support-for-plantuml.html

[mwwhited]

Not a fan of the GPL license on plantuml but the features are much nicer than mermaid (though mermaid is a bit nicer to look at.)

[KevReed]

PlantUML is available under MIT licence among others, with a few features removed which depend on GPL software. See https://plantuml.com/faq.