Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhance documentation on MarkBind's built-in PlantUML support with examples #88

Open
mfjkri opened this issue Sep 25, 2024 · 3 comments

Comments

@mfjkri
Copy link
Contributor

mfjkri commented Sep 25, 2024

Situation

Currently, in the PlantUML guide, there is a section about using MarkBind with PlantUML.

Saving the Diagram as an image

  • When using MarkBind as the site generation tool:
    • MarkBind has built-in support for PlantUML. The diagram will be generated and saved as an image automatically. No additional work needed from you.
  • When using Jekyll as the site generation tool:
    • The PlantUML integration plugin allows you to export individual diagrams to a location of your choosing. Click the Save Current Diagram Only button and choose the location to export the image file.
    • You will have to git add any new diagrams generated!

Problem

It lacks details on how the built-in support works. The current text might leave users uncertain about what this support entails and how to fully use it. This was something I faced while working on an earlier PR.

Proposed Solution

Expand on the explanation by providing a few examples of how to use PlantUML with MarkBind, giving users more clarity on its built-in support.


(Elaboration to be added)

To link to an external .puml file, add this line to your markdown:

<puml src="path/to/your/diagram.puml" width=300 />

Alternatively, you can embed the diagram directly within the markdown:

<puml width="300">
@startuml
Alice -> Bob : Hello
Bob -> Bob : Self-call
Bob -> George : Create
@enduml
</puml>
@damithc
Copy link
Contributor

damithc commented Sep 25, 2024

@mfjkri Good point. But describing how to use PlantUML in MarkBind should be MarkBind's job.
Perhaps we add a note on how to use PlantUML with Jekyll and MarkBind, with the latter pointing to https://markbind.org/userGuide/components/imagesAndDiagrams.html#plantuml-diagrams ?

@mfjkri
Copy link
Contributor Author

mfjkri commented Sep 25, 2024

Hi Prof, I agree with your suggestion! If we add this note to the PlantUML guide, I believe it would fit well directly under the “Saving the Diagram as an Image” section (which is part of the broader “Creating/editing/exporting diagrams” section).

I’ve attached an illustration for clarity.

IMAGE 2024-09-25 12:49:20

Would this be suitable or would there be a better way of representing this note?

@damithc
Copy link
Contributor

damithc commented Sep 25, 2024

Would this be suitable or would there be a better way of representing this note?

@mfjkri Yes, I think so. Go ahead if you plan to submit a PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants