I recently participated in the design of several new projects, which required a lot of design document writing, such as class diagrams and flowcharts. Of course, there are many good drawing tools, such as Visio, StarUML, draw.io, etc. However, they all have a fatal flaw (at least for me), that is, they all completely rely on GUI operations and cannot rely on DSL to write legends. This approach has several problems:
- Inefficient. The speed of dragging and clicking with a mouse definitely can't match keyboard input.
- The need to open an external tool for editing, and the inability to complete document writing within the editor, creates a sense of discontinuity that significantly affects the design process.
- Unable to incorporate legend design into version control.
So I searched online for a long time and found a format called PlantUML. This is a tool that relies on DSL to draw UML diagrams. It can be understood as similar to Markdown, using a specific markup language to enhance the visual effect of ordinary text.
In fact, PlantUML has already been incorporated into many Markdown editors as a standard, allowing PlantUML to be directly inserted and rendered in Markdown. However, Github does not currently support this, so when we write documents, we still need to specifically create ***.puml files for writing.
Here I recommend a small tool under IDEA: PlantUML integration. It can render the effect in real time while writing the legend.
PlantUML supports many types of diagrams, which can be said to be very powerful. You can directly refer to the Chinese documentation.
PlantUML is an open-source project that supports quick drawing of: Sequence Diagram Use Case Diagram Class Diagram Activity Diagram Component Diagram State Diagram Object Diagram Deployment Diagram Timing Diagram
It also supports the following non-UML diagrams: Wireframe graphical interface Architecture diagram Specification and Description Language (SDL) Ditaa diagram Gantt chart Mind map Work Breakdown Structure diagram Mathematical formulas with AsciiMath or JLaTeXMath symbols Entity Relationship diagram
Finally, let's talk about how to integrate and manage PlantUML in documentation.
Engineering documents like these are very suitable for management with Git along with the code, which is what I do. But Github does not support rendering PlantUML, so when viewing documents on Github, do we need to download the PlantUML documents and then use the plantuml tool to render the images? The answer is no, PlantUML has already provided us with a solution - PlantUML Server, the server can directly render images for the front-end display. And www.plantuml.com also provides rendering services for free.
https://www.plantuml.com/plantuml/proxy?src=RESOURCE&idx=INDEX&fmt=FORMAT
- src: puml source document address, if the document is hosted on github, you can directly get the cdn address of the file.
- idx: If the document contains multiple UML blocks (starting with @startuml and ending with @enduml), you can use idx to specify which UML to render.
- fmt: Output format, the default is png. This might be due to the server limiting the maximum file size, so rendering as png might result in incomplete images. It is recommended to set it as svg, firstly to reduce bandwidth consumption, and secondly to ensure the image is clear enough no matter where it is displayed.
In this way, we can directly insert PlantUML as an image into the Markdown document on Github.