vscode Archives

Mermaid.js is one of my recent favorite tools I’ve added to my toolbox. Mermaid.js is an open-source diagramming tool that converts plain structured text and renders diagrams as SVG or PNG images. You can use the following tools to render and save mermaid diagrams on your documents but there are better ways to create, edit and maintain your mermaid diagrams in your favorite documentation tools. Because of its popularity, a lot of documentation tool supports the mermaid either out of the box or with add-ons.

Mermaid Live Editor

Let’s start with the obvious option. Mermaid.js has an online editor that is free to use and does not require anything. You can quickly start creating diagrams, and share or embed them in your favorite places.

Try: https://mermaid.live

Markdown editors mermaid support

I personally use Visual Studio Code as my markdown editor and I use the Markdown Enhanced Preview extension to preview additional markdown features that include mermaid syntax to be rendered as diagrams.

https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced

I’ve seen most of the text editors that have markdown support to have mermaid support included by default or with add-ons/extensions.

Documentation tools mermaid support

Most tools work with markdown or support markdown features, recognize mermaid.js, and provide out-of-the-box mermaid diagrams support.

Github.com markdown mermaid support

Github started to support mermaid diagrams rendered instead of code blocks if the code block is marked as mermaid syntax.

Include diagrams in your Markdown files with Mermaid

It works out of the box and when a markdown file is rendered in the preview mode in your repo, it will show the diagram as SVG rendering inline instead of the code block.

Confluence mermaid Plugin

There is a free confluence add-on that adds a page macro that you can insert a mermaid diagram by adding the source diagram text once you insert it to the page, it renders it as an SVG image. It can be easily edited on the page so there is no need to render, export, and insert as an image manually.

https://marketplace.atlassian.com/apps/1222792/mermaid-integration-for-confluence?tab=overview&hosting=cloud

Notion mermaid support

Any code block that is selected as mermaid syntax, gets a mermaid diagram rendered in the code block. It has diagram size limited to the code block width which makes it hard to see large diagrams, but it does render small-size diagrams or things like pie charts powered by mermaid syntax well.

There are probably tons of both diagramming tools as well as wireframing tools out there. And I have been using most of those throughout my profession.

I want to talk about my recent favorite “excalidraw” that I made it a quick-note style using its Visual Studio Code extension and some bash + Alfred automation on mac (that can be easily replicated in other OSes).

Let’s start with what Excalidraw is…

Excalidraw is an open-source, react-based, web-based drawing tool. It comes with a limited set of functions in a minimal control panel but the batteries-included for all you need – for what it does in my opinion.

It’s a diagramming app after all. But not just that.

It’s Open source

https://github.com/excalidraw/excalidraw

It’s portable – No app is required

Available at https://excalidraw.com/

It stores and auto-saves your open file in the local storage.

It also has some collaborative online real-time editing mode which is awesome.

Saves editable copy inside share-ready PNG or SVG files

A very smart thing excalidraw does is save its editable meta in PNG or SVG exported/saved file. It definitely makes the file size larger, if you are using a lot of bitmap icons, screenshots, and all. If not, the png file you save and slap in slack, emails are actually going to be excalidraw openable and editable.

The easiest way to do this without any option is to name your file with .excalidraw.png or .excalidraw.svg extension. When opening this file with excalidraw online or VSCode, it will automatically open the editable version in less than a second. You make edits and just save…

Embeddable

If you are developing a react-based application, you can actually embed excalidraw as part of your app and provide diagramming support.

import { useState, useEffect } from "react";
export default function IndexPage() {
  const [Comp, setComp] = useState(null);
  useEffect(() => {
    import("@excalidraw/excalidraw").then((comp) => setComp(comp.default));
  }, []);
  return <>{Comp && <Comp />}</>;
}

https://www.npmjs.com/package/@excalidraw/excalidraw

Have a component library with everything you’ll need

https://libraries.excalidraw.com/

VSCode Extension

Even though I love it runs on the browser and auto-saves. I prefer to have this ready under my toolkit offline or faster open/edit/save files.

If you are a developer, good chance that you are using vscode daily – Or if you don’t, vscode is a very lightweight editor that is worth to use it only for excalidraw. For the ones who uses vscode actively, this means no extra tool is needed. Both vscode and excalidraw renders very fast and don’t use much system resources.

Another magic feature I like using excalidraw in its VSCode extension is that you just open .excalidraw.png (or svg) files by dragging and dropping them in vscode, making edits, and save. No export/re-export is needed. You can just use the saved PNG which includes both the final rendered PNG and the source content in the same file.

This also makes a lot of sense for teams who use their codebase to document their stuff in markdown files. Excalidraw diagrams are the perfect companion for CVS-stored documentation.

Quick Create Digram

A final trick I do that makes my day-to-day very convenient is, having a shortcut to create an empty excalidraw.png file on my desktop and open it in VSCode, so I can start diagramming or wireframing in seconds without needing to open the wireframe app, create a new empty project or file…

The way I do this is by having a bash alias that is registered in my dotfiles/my-aliases: ned abbreviation of “New Excalidraw file on Desktop”.

function ned(){
  OLD_IFS="$IFS"
  IFS='-'
  NED_FILE="$HOME/Desktop/$*.excalidraw.png"
  IFS=$OLD_IFS
  echo "Created $NED_FILE"
  touch $NED_FILE
  code $NED_FILE
}

Then calling this alias either from the command line (if I’m already there) or by using an Alfred custom workflow that calls the same bash alias.

Then viola, start dropping things from my library and quickly wireframing an idea I’m thinking:

And finally, just save and share the png file in your favorite way…

Happy diagramming, wireframing ✍️

Tag: vscode

Editing and previewing Mermaid diagrams on your docs (markdown, github, notion, confluence)