![]() There is no need to wait for the support of the diagramming tool in the document markup language. Since the meta markup is language agnostic, it can be used with any existing and future document markup languages. The meta markup should be responsible for the integration. The diagramming tool should be responsible for the diagramming. The document markup language should be responsible for the document structure and content. The basic idea is not new: separation of concerns. This meta markup can be document markup agnostic and support all the diagramming tools you want to use. The solution is to use a meta markup above the document markup. It is a separate concern with the document’s programmability ensuring document consistency automation. The principal reason for this is an architectural mismatch.ĭocument markup languages must be responsible only for document structure and content and nothing else.Įmbedding a diagramming tool into the markup language must not be implemented in these languages. There will always be a new tool you want to use, and you will have to wait for the support of that tool in your favorite markup language. The latter approach, however, will always remain an issue. You can abandon your ideas, stick to the available tools, or wait for a solution. What happens, however, if you want to include Mermaid in Asciidoc? What if you need PlantUML in Markdown? How do you solve the issue if you want to host your Markdown elsewhere besides GitHub? You can include PlantUML diagrams in Asciidoc documents. You can include Mermaid in Markdown documents if you target GitHub hosting for your document. To solve these problems, more and more markup languages support selected diagramming tool markups to embed in the text. It is also a good idea if you can parameterize the diagram, and you could avoid copy-pasting diagram parameters from the document, the documented code, or the other way around. The more distanced the two corresponding and related parts are, the more likely that one or the other becomes stale when the other is updated. ![]() It is easier to keep the consistency of the documentation when the different parts are close together. Keeping diagrams in separate files has advantages, but also disadvantages. When documenting some systems, it is often necessary to include diagrams. However, before anything else, here is a demonstration image, which was created the way I will describe in this article. The technique works for Markdown, Asciidoc, APT, or any other text-based markup language. This article will show how you can integrate any diagram-as-code tool into your documents. What can you do, however, if you use a different editor? What if you want to use your Markdown document in an environment that does not integrate Mermaid yet? What can you do if the diagram is not Mermaid but PlantUML, Graphviz, or any other diagramming tool? It is also integrated into several editors (see " Include diagrams in your Markdown files with Mermaid" for more information). A year ago, it was integrated into the Markdown rendering of GitHub. I intend to convert all of my third party diagrams to Mermaid ASAP, so they can be properly tracked / access controlled, whilst also being far easier to work with than a GUI driven tool.Mermaid is a trendy diagramming tool. Being able to include diagrams of classes, databases, user journeys etc in a PR / wiki without a third party service is something I’ve desperately needed! The fact that they’re just code also means they can be stored with the codebase, instead of a / images / folder or hosted elsewhere. Overall, I can’t believe this GitHub feature isn’t more widely known. New versions are being regularly released, with lots of features and fixes! Summary For example when included in a table it seems to reserve space for itself at full size, then shrink down, leaving a big gap:įinally, the changelog on the documentation site is very outdated. Thirdly, whilst it is extremely powerful, it has quirks. The git graph feature is experimental, and isn’t in their documentation at all! For example every aspect of flowcharts are documented, whilst user journey has a single example. Secondly, the official documentation quality varies a bit. For example, the Gantt chart above doesn’t work locally for… unknown reasons. This makes writing them very easy, but be aware that the local preview CAN differ slightly from GitHub’s. They can all be embedded in GitHub PRs / issues / wiki pages, and include:įinally, I wanted to mention a few things I discovered whilst learning Mermaid’s capabilities.įirstly, since Mermaid is essentially a Markdown extension, extensions for VS Code (and other text editors) exist for realtime previewing. To learn the capabilities of Mermaid, I wrote cheatsheets for all supported Mermaid charts.
0 Comments
Leave a Reply. |