Diagrams as Code with Mermaid, GitHub, and Visual Studio Code

Summary

In this video, DevOps Toolkit creator showcases how developers can create diagrams as code using Mermaid, a tool that enables you to write and visualize diagrams directly in markdown files. Visual Studio Code and GitHub integrate seamlessly with Mermaid, offering a sophisticated environment for developers to maintain documentation alongside their code. The video demonstrates the use of various diagram types such as flowcharts and Gantt charts, while GitHub Copilot significantly aids the process by offering smart code suggestions. Mermaid proves to be an essential tool for developers who prefer code-based solutions, enhancing both productivity and documentation precision.

Highlights

• Discover how to use Mermaid for creating diagrams as code and visualize them seamlessly in GitHub and Visual Studio Code 🚀
• Learn the benefits of keeping your diagrams as living documents, easily updatable and integrated with your code 📈
• Mermaid supports various diagram types: flowcharts, sequence diagrams, Gantt charts, and many more 🎨
• Utilize VS Code and GitHub for an efficient workflow, no more dragging and dropping in GUIs to create diagrams 🎯
• GitHub Copilot assists you in drafting diagrams quickly by offering smart suggestions on-the-go 🤖

Key Takeaways

• Mermaid allows developers to create diagrams as code within markdown files, making diagrams a part of your version-controlled documentation 🌟
• Visual Studio Code offers tools to write and preview these diagrams, integrating them smoothly into your development workflow 💻
• GitHub enhances the experience by visualizing diagrams directly from your repos, making documentation more robust and dependable 📚

Overview

Creating diagrams for complex projects can become cumbersome if you rely on graphical user interfaces. But with Mermaid, a tool to create diagrams as code, developers can now integrate these into their coding workflow with ease. Whether it's flowcharts or Gantt charts, Mermaid supports them all, making it a versatile solution for various diagram needs.

Mermaid leverages markdown files, allowing you to code your diagram structures and preview them instantly in Visual Studio Code. GitHub further integrates this workflow by visualizing these diagrams directly from your repositories, ensuring that your diagrams are always part of your project documentation.

Thanks to GitHub Copilot, drafting diagrams becomes even simpler as it provides intelligent suggestions, reducing manual effort and enhancing productivity. If you're a developer looking to maintain technical documentation close to your code, Mermaid, along with GitHub and Visual Studio Code, provides an efficient and innovative solution.

Chapters

• 00:00 - 00:30: Introduction The chapter titled 'Introduction' discusses the common need for creating diagrams and the typical approach people take by searching online for tools. It highlights that most search results will lead to graphical user interface (GUI) tools, such as desktop or web applications, but suggests that the author is looking for something different.
• 00:30 - 01:00: Software Engineer's Preference The chapter titled 'Software Engineer's Preference' discusses a software engineer's workflow and preferences, focusing on the central role of plain text formats in their work. The engineer writes code, creates scripts, and drafts documentation, all of which are stored in version control systems like git. This approach emphasizes the importance of machine-readable formats in software engineering.
• 01:00 - 01:30: Using Visual Studio Code The author explains that while they use graphical user interface tools to observe the results of work, all their work is primarily conducted through Visual Studio Code. This software serves as their main graphical user interface, enabling file browsing, code writing, text editing, and terminal commands. Aside from a browser and Slack, Visual Studio Code is the sole tool they use extensively.
• 01:30 - 02:00: Creating Diagrams as Code The chapter discusses the advantages of using Visual Studio Code for creating diagrams as code. The author prefers this method as it's faster and less error-prone compared to using GUI tools. This approach allows for more efficient command execution and coding precision.
• 02:00 - 02:30: Introducing Mermaid The chapter begins with the author's desire to utilize diagrams as a form of coding, driven by the need to visualize these diagrams within GitHub repos and preview them in Visual Studio code. It had been some time since the author last created diagrams, but a recent project necessitated their use. This set the author on a quest to find an effective method to create and manage these diagrams as part of their coding workflow.
• 02:30 - 03:00: Creating a Flowchart with Mermaid This chapter discusses the use of Mermaid, a tool for creating diagrams as code. The author describes Mermaid as an ideal solution for writing diagrams in Markdown files, previewing them in VS Code, and visualizing them in GitHub repositories. Despite being an older tool, it fits the author's needs perfectly for diagram creation.
• 03:00 - 03:30: Working with Nodes and Links The chapter "Working with Nodes and Links" introduces the concept of using Mermaid for diagram creation.
• 03:30 - 04:00: Adding Styles and Links This chapter explores various features of markdown using Visual Studio Code. It demonstrates how to open a markdown file and a preview simultaneously, showcasing the typical actions one can perform, such as writing titles and descriptions within markdown. The emphasis is on the abundant features available in the editor.
• 04:00 - 04:30: Branching and Grouping Nodes This chapter covers the basics of using Mermaid diagrams within a markdown file. It starts by explaining the importance of using three ticks to write a code block, especially when integrating Mermaid diagrams. The chapter briefly touches on skipping the basic Markdown features to focus more on the specifics of Mermaid, a tool for creating diagrams easily within text files, enhancing documentation clarity and structure.
• 04:30 - 05:00: Advanced Features of Mermaid The chapter discusses advanced features of Mermaid, particularly the flowchart type. It explains how to begin by setting the type and direction of the chart, in this case using a top-down (TD) configuration. The transcript notes that GitHub Copilot provides suggestions, which may seem irrelevant initially but are expected to improve with continued use.
• 05:00 - 05:30: Exporting and Visualizing Diagrams This chapter discusses the advantages of using the tool 'Co-pilot' in conjunction with Mermaid for creating diagrams. The author appreciates Co-pilot for its ability to provide intelligent suggestions as they develop their charts, which enhances productivity and creativity. The chapter suggests that viewers unfamiliar with Co-pilot can find a video link for further education on its functionalities. Moreover, it hints at a preview feature within the charting process.
• 05:30 - 06:00: Real Project Example The chapter 'Real Project Example' begins with the speaker acknowledging some resolution issues with their setup, which are affecting the display. The speaker assures the audience that the setup usually works well under normal conditions. The main task described is defining the first node of a chart, which is named 'setup.dev'. The speaker also mentions the option of adding text in brackets if a different name is preferred for the text, separate from the node's name.
• 06:00 - 06:30: Evaluating Mermaid The chapter titled 'Evaluating Mermaid' discusses the process of creating and naming nodes using a tool that provides a visual interface, possibly a flowchart or diagram software. The speaker explains how to create nodes with rounded corners and how to give them names that are either symbolic or more descriptive for better understanding. There is a specific example of creating a node named 'BCI' with the descriptive text 'Build Container Image in Dev.' The chapter also mentions dealing with some technical issues, as the preview feature in the tool is not functioning properly, leading the speaker to attempt troubleshooting by closing and reopening files.
• 06:30 - 07:00: Conclusion and Recommendations In the conclusion and recommendations chapter, the focus is on technical instructions regarding the setup of nodes and building container images in a development environment. The speaker notes a preference for changing the node shape from rounded square to circle by altering the bracket format. The adjustment of the preview is emphasized for resolving display issues.

Diagrams as Code with Mermaid, GitHub, and Visual Studio Code Transcription

• 00:00 - 00:30 sooner or later everyone needs to create a diagram or maybe a few when that time comes majority of people will consult Google by searching something like diagrams or diagram tool or diagram maker and all the results at least on the first page of Google search will likely be leading towards a graphical user interface or GUI type of a tool it could be a desktop application or a web application but that's not what I want
• 00:30 - 01:00 [Music] foreign software engineer first and foremost I write code and I store it in git I read scripts and I store those scripts in git I write documentations markdown files and I store those in git as well you get the point right almost everything I do is done in plain text format and it can be interpreted by machines and it's
• 01:00 - 01:30 stored in git I use graphical user interface tools only to observe the results of my work not to do the work itself with one notable exception everything I write or do is done through Visual Studio code that's my graphical user interface it allows me to browse files to write code or any other text and it gives me a terminal to run commands except for a browser and slack it is the only and I repeat only tool that
• 01:30 - 02:00 constantly runs on all my machines now the reason why I use Visual Studio code for almost everything is very simple it is faster and less error prone for me to write everything as code and run commands than any other way of doing things it is certainly faster and better than clicking buttons and dragging and dropping stuff in a GUI tool now you might be asking hey why is Victor talking about this well
• 02:00 - 02:30 I wanted to create diagrams as code to keep that coding git to visualize those diagrams in GitHub repos and to write and preview those diagrams in Visual Studio code now it's been a while since I needed to create diagrams but all that changed a few weeks ago I started working on a project that would greatly benefit from a diagram actually from a set of diagrams so I started on a mission on finding a way to do it from
• 02:30 - 03:00 vs code I wanted diagrams as code type of solution and I found just the right tool it's not a new one it's been around for a long while but I haven't used it that heavily in the past and that's something is called mermaid it allows me to write a diagrams as code it allows me to write them inside markdown files it allows me to preview them in vs code it allows me to visualize them in GitHub repos all in all it's just the solution I need and I
• 03:00 - 03:30 want to share it with you today to begin with mermaid allows us to create almost any type of diagram known to men it can be a flow chart or a sequence or a gun chart or a class diagram or git flow or entities relations between entities now as always I will not continue speaking for long that's boring so let's jump into Henson part let me create a diagram
• 03:30 - 04:00 and while doing that explore some of the many and I repeat many features it offers so here's my visual studio code in a lower resolution mode so as you can see it well and I have a markdown file open on the left side and I have a preview open on the right side and I can do the things that you normally do in markdown I can write the title and I can write some description now you already know
• 04:00 - 04:30 all that so I'm going to skip that part skip what you can do in markdown and jump straight into mermaid right we can create mermaid diagrams just by writing a code block and code in markdown is surrounded by three ticks it could be one tick but don't do that with three ticks and we typically specify the type of the code we want to present and in this case that's Mermaid so that's how GitHub and vs code know that this is
• 04:30 - 05:00 mermaid something no it all starts by defining the type of the chart we want and today I'm using flowchart and that is followed in this case by TD meaning top down so I want top down not left right or right left or whatever other options are I want the top down flowchart what you will notice is that GitHub copilot is kicking in and offering suggestions at the very beginning those suggestions are kind of silly but they will improve over time
• 05:00 - 05:30 actually co-pilot is one of the big reasons why I like mermaid because once I develop once I progressed with my chart it started offering intelligent suggestions which is absolutely awesome so do not write my charts all by myself I use copilot for that if you're not familiar with copilot the link is over there there's the video I created it's just watch it not now later now another thing before we proceed that you will notice is that there is a preview on the
• 05:30 - 06:00 right side it's not working perfectly well today but that's mostly I think because my resolution I lowered the resolution drastically so that everything is bigger so as you can see it well on your screen but you need to trust me that it works well most of the time anyways let me Define the first node of a chart I'm going to call it setup.dev and then in Brackets I'm going to put a text right so if you don't want the text to be the same as the name of a
• 06:00 - 06:30 node then you just put it in brackets for now and you can see on the right side that we got a tiny box with rounded Corners called setup and I'm going to create a second node I'm going to call it BCI and since this is not understandable to everybody but it is good as the name of the node I'm going to put the text in Brackets build container image in Dev as I mentioned earlier the preview is freaking out today I'm not sure why so I'm going to close the files and open it again to
• 06:30 - 07:00 refresh the preview and hopefully that will fix the issue and there we go now it's working well so I have two nodes so far setup and build container image in Dev sometimes you might want to change the shape of a node so for example I might want to depict setup as a circle instead of rounded square and I can do that by changing the form format of the brackets for something else and in this case Circle is double brackets so if I
• 07:00 - 07:30 surround set of text the double brackets I get the circle now the question comes how do we connect one node with another and we can do that by typing the ID of one node which is set up Dev in this case and then dark Dash greater than and then the second name of the node the name of the second node and you can see that those two got connected right now sometimes you might want to enable people to click on some node in a graph and be redirect it somewhere else to
• 07:30 - 08:00 create a link and we can do that by saying Hey whenever somebody clicks on in this case PCI this is the link where they should be redirected and I wanted to open in a blank page blank top a new top now blank instruction does not really work in GitHub but it works in other places anyways you can create links as well what else can we do well we can do actually many things but what should I show next yeah let's change the color of the no the fun of the notes and
• 08:00 - 08:30 we can do that by specifying Style I want to style PCI and I can do many things with Styles in this case I'm going to fill it with blue color and poof now it's blue so let me create a couple of more things let's say that I want to Branch from the blue box now into a couple of boxes so I'm going to create BCI Lima that's going to be one option to build with Lima and I'm going to connect those two by saying BCI dash
• 08:30 - 09:00 dash greater than BCI Lima and then I'm going to specify a second node which would be about buildbox that's a second way how we can build images I'm going to connect it with the general purpose build one by saying hey BCI dash dash you know BCI build box and I'm going to create a third branch which will be PCI kbld because that's the third way we you can build stuff with Carvel kbld or Carvel K build and I'm going to connect it with PCI as well by typing BCI build
• 09:00 - 09:30 and then after I present all the options I can create another one and say hey now you need to store in a registry your image image that you built and the registry will be used no matter which build method we used so it means that I'm going to connect the three nodes Lima buildbox and kbld K build with the registry node I'm going to paint it blue voila I have a diagram of flow of very
• 09:30 - 10:00 beginning of a flow that starts with building an image using different tools and then going for a registry where we should push images and I can change color of that I you I tend to use red when I want to say I haven't finished the code for this part yet anyways we can study differently we can connect it differently the arrows you're seeing can be shaped differently as well there's a lot of customizations a lot of options
• 10:00 - 10:30 that we can employ when using mermaid sometimes we might want to group things into sub graphs into group of nodes subgraph and we can do that by saying hey there is a subgraph called Dev in this case everything that is within it and until it ends with end instruction is one subgraph and then it will paint it within another box yet another box and I will create yet another subgraph
• 10:30 - 11:00 called previews after we build image and what's an art we might want to jump into going and creating previews of our application so that's another subgraph and I can connect not only nodes of the graph but also sub graphs by using the same logic as before Dev Dart Dash greater than previews I can connect anything with anything with any many of the types of connectors even though I'm using arrows today and what else should I do actually I will let you explore it
• 11:00 - 11:30 yourself I can add more notes and do the things do almost anything that I need to do to create graphs the only thing I cannot do is control exactly where each box will be but that's silly to do because the moment we change graphs it should change dynamically instead of fast tracking and dropping things right and once we're finished and finished writing the code and finished previewing it seeing how it looks like the last
• 11:30 - 12:00 thing missing is to export or visualize our graph our diagrams so that others can see it others can use it there are many ways we can do that there are some node.js libraries we can export them to files and so on and so forth but I'm not going to do any of those what I'm going to do is simply push this file to git triple and then let GitHub visualize it for me as part of my breed Mirror part of my markdown now I'm not going to push this file there I'm going to push the
• 12:00 - 12:30 one that I'm working on right now and actually I already pushed it but I'm going to show it to you how it looks like from GitHub so let me navigate to the file in question and there we go that's the graph that I'm working on right now this is a real thing this is not a demo and mermaid was a perfect fit I love it and by the way I'm revealing something that I shouldn't reveal because this is kind of a secret this is a big thing that me and Whitney are
• 12:30 - 13:00 working on in 2023 so far uh I'm not going to tell you anything but it's very exciting and you should look for it in late January more or less we'll start a big project for which I need diagrams and I hope that you will like it but anyways let me go back to the subject let's talk about mermaid should you use it is it the right thing for you
• 13:00 - 13:30 if you want to have living documentation that is easy to update you almost certainly want to keep that documentation close to the code or projects it documents that means that you might want to keep the docs in the same repository as the code if diagrams are part of the documentation it makes sense perfect sense to Define them in same markdown files as the rest of the documentation instead of creating them somewhere else and then exporting images
• 13:30 - 14:00 and then embedding them into the docs and you know all the madness that we've been doing in the past anyways and probably most importantly if you are a developer you're likely not the person that likes getting things done by clicking buttons and dragging and dropping stuff that's why mermaid is amazing it is a perfect tool for developers to create diagrams it is code so an ID like vs code is a perfect tool
• 14:00 - 14:30 to write and preview mermaid diagrams vs code preview might be a bit rough around the edges especially while writing it might not refresh itself perfectly but it works most of the time what I didn't mention is that for you to get preview or mermaid you need to install an add-on but that shouldn't be a problem so just install the other another Plugin or whatever it's called in vs code or whichever editor you're using on top of all that the ability to display diagrams in GitHub repos is a huge plus even if
• 14:30 - 15:00 GitHub is not your thing there are plenty of other ways to visualize mermaid or to export diagrams in as images so check out the documentation personally I love GitHub and I love the fact that you can just visualize it as part of your markdown in your GitHub repos finally and equally important GitHub Pilots ability to offer suggestions is a cherry on top of the cake it helped me a lot I'm just start
• 15:00 - 15:30 typing something for mermaid and co-pilot would finish it and most of the time after a bit of training it worked perfectly all in all mermaid combined with GitHub and with Visual Studio code is absolutely awesome use it if you need diagrams and you are a developer if you're not a developer if you're not engineer and you are let's say manager well I mean I'm certain that you are not since you would not reach this far into
• 15:30 - 16:00 this video so my advice for non-engineers does not matter in this case thank you so much for watching see you next time cheers foreign