Feature request: convert PlantUML code block to markdown image and vice-versa

[fuhrmanator]

I use markdown a lot, and PlantUML a lot, and VSCode a lot. Currently I'm doing my slide presentations using Reveal.js, and it's cool that I can see a preview of my plantuml diagrams when showing the markdown preview of VSCode. However, since there is sadly no markdown support for PlantUML when I generate the reveal.js presentation, I only see the plantuml source in the final presentation.

So, a cool feature would be to use the standard markdown, e.g.:

```plantuml
@startuml Here's a sequence diagram
A -> B : hello
@enduml
```

but there is a function in the extension to "Convert PlantUML block to markdown" where it would replace it with

![Here's a sequence diagram](https://www.plantuml.com/plantuml/img/SrJGjLDmKh1Io4ZDoSa70000 "Here's a sequence diagram")

which of course would render like in the final reveal.js presentation.

There would be a feature to transform the markdown image back to the code block, in case I want to edit it.

The early days of PlantUML's Microsoft Word macros worked like this.

Perhaps a right-click inside either the PlantUML source block or the markdown would be how you would access the commands to convert? I have never coded a VSCode extension, so I don't know how much context can be gathered from the cursor.

I know there is a feature to "export current document's URLs" but they go to an output terminal, and so it's tedious to copy/paste them. It would be cool if they would just replace the block inside the original document.

[qjebbs]

It's not only about the url convertion itself, but to meet the markdown specifications.

Consider we have indented plantuml blocks, we have to keep the indent between conversions.

```
- diagram 1

    ```plantuml
    @startuml Here's a sequence diagram
    A -> B : hello
    @enduml
    ```

- diagram 2

    ```plantuml
    @startuml Here's a sequence diagram
    A -> B : hello
    @enduml
    ```
```

Detecting a plantuml block is also a problem, consider:

```
// these are codes, not a diagram, should not be converted.
```plantuml
@startuml Here's a sequence diagram
A -> B : hello
@enduml
```
```

Even we don't have ``` sorroundings, but if it's indented, it's not a digram too. Consider the following Markdown code:

## title

content.

    here are codes, not a digram
    ```plantuml
    @startuml Here's a sequence diagram
    A -> B : hello
    @enduml

You see, I need a markdown parser to do it right, and lots of things.

Anyway, if any one like the feature, and is able to do it, PR is welcome.

[fuhrmanator]

Those are good points. I agree it would not be easy to do it correctly for an entire document.

What about allowing the feature to work when your cursor is inside a block to convert (not the whole diagram)?

So, user clicks inside a block, chooses Convert to image. In theory, the algorithm just goes back until a @startuml (without @enduml) then goes forward to @enduml (without @startuml). If the user converts the wrong diagram, it's her mistake.

The same strategy could work for diagrams to go back to source.

[jan-hudec]

"Convert PlantUML block to markdown" where it would replace it

Wouldn't that prevent you from further editing the diagram? Or require going through all the parts before generating the presentation?

generate the reveal.js presentation

The generator is better place to drive the generation so the original files are not modified in the process. I've done this with pandoc and there is a plantuml filter for it.

Or, since reveal.js can process the makrdown when showing the presentation in the browser, add the conversion there (using a plantuml server). The marked library does seem to have appropriate hooks.

[fuhrmanator]

Wouldn't that prevent you from further editing the diagram? Or require going through all the parts before generating the presentation?

No, in fact it's reversible. I've coded it in several languages. Take this example diagram:

![PlantUML diagram](https://www.plantuml.com/plantuml/img/7Sqn3i8m44JHtgUOZb30IH898UK0AtimAvnTopODfyTGV-dzmanBuLR4nhwjr-Z7gKCFoSH-NpkYsn0r23vQAnEMIz4NpmYDjR5pvg5ky0V6aqWgkSaFwVvkaHD83FE1ybzz0G00)

As a proof, if you change the /img/ part of the URL to /uml/ (edit: and you use http rather than https) you can see the source on PlantUML's site.

There's also (at least) one Node package: https://github.com/markushedvall/plantuml-encoder#decode-example

The generator is better place to drive the generation so the original files are not modified in the process.

I also use Pandoc the way you describe to make documentation via LaTeX and it's awesome.

However, there are many use cases. I like to write Readme files that are used on GitHub, which does not render plantuml diagrams stored in code fences, and linking them to your Readme as .puml files is tricky (although possible), and breaks when repos are cloned (because you have to use a link to a raw source). If the function I requested worked, I could keep it all in the Readme, but of course I'd have to be comfortable with PlantUML.com rendering the images (but it's public github).

[stephanedenis]

If you want a behaviour similar to what you have in VSCode, you can use my version of MDWiki (https://github.com/stephanedenis/mdwiki) to display PlantUML on the docs folder (project web site) in GitHub. See https://420-geq-hy.github.io/ProjetB/#!Arch/UseCases/index.md for example. The markdown is processed on the browser and the ```plantuml blocks are converted to SVG so the hyperlinks of your PlantUML code are functional.

[jan-hudec]

I like to write Readme files that are used on GitHub, which does not render plantuml diagrams stored in code fences

That's a good motivating use-case indeed.

[dukk]

I think doing something like what draw.io's extension does would work well for PlantUML and probably help this situation. Basically if you take a file with a .drawio.png or .drawio.svg it'll auto export and embed the drawio file inside the png or svg file. Then you can just reference the file as a png or svg in markdown. Would be nice to do the same thing with .puml.png/svg files.

[chipbite]

I think doing something like what draw.io's extension does would work well for PlantUML and probably help this situation. Basically if you take a file with a .drawio.png or .drawio.svg it'll auto export and embed the drawio file inside the png or svg file. Then you can just reference the file as a png or svg in markdown. Would be nice to do the same thing with .puml.png/svg files.

Yes, exactly this! Would this be possible?

So

• opening a test.puml.png in vscode would open the text editor with only the embedded plantuml code.
• Saving the file would create a render, update the image and the embedded code and save. And of course,
• previewing the file would work as today, basically.

[chipbite]

I took the time to create a ticket / request / idea for this: https://github.com/qjebbs/vscode-plantuml/issues/434