Graphviz and hierarchical graph layout: a review and plugin proposal

I’m currently making an issue tree, and Graphviz is a powerful tool for this, but I wish I can make it with Obsidian because Graphviz alone (even with VSCode) don’t have:

  • Linking suggestion
  • Auto update links
  • A place to provide more details of a node

Now, you may ask, why don’t I use Mermaid, or the Obsidian plugins for Graphviz, PlantUML, Charts View, Argdown, Mindmap,, Corkboard, Juggl (whose hierarchical layout is from dagrejs), Excalidraw? Well, they cannot substantively customize the graph as what Graphviz has. In particular they don’t have all of these features at once:

  • Specifying the rank of the nodes (e.g. aligning a child node of branch A to be in the same rank of a grandgrandchild node of branch B)
  • Automatically generating a graph. For graphs with a lot of nodes, adding a single new node may require you to significantly remap the whole structure
  • Making the graph of all of my notes, not making a graph inside a note

For now to generate a .dot file you have two ways:

All of these require you many clicks to get the file. Even when I have been familiar with both Cytoscape and Neo4j, and have used the first route a couple times, I still need to significantly refine the output to serve my need.

Since it seems that no one has done this before, I guess I will need to do this.

Other discussions on the forum that also mention Graphviz or hierarchical layout: Diagramming support, Graph Visual Hierarchy, Adding A Tree Chart Graph View, Graphviz from links, Graph View Parenting system, Export Graph to a network graph format, Export to common graph formats, Generic Graphics Plugin, Obsidian graph to gephi, Making mindmaps from notes a graph with a defined semantic relation, Concept map plugin idea


v0: Do it for my need

It will just be a script that reading the JSON files from Breadcrumbs and converting it to .dot format. It will have no UI, and you need to be familiar with GraphViz first. It is not even an Obsidian plugin.

Feature: auto wrapping label

Status: done

v1: Make it an Obsidian plugin

It will export a .dot file with more features like:

  • HTML title for metadata (e.g. index, alias, etc)
  • Style based on tags

v2: More features

  • Need not to install Metadata Extractor beforehand
  • Need not to learn GraphViz beforehand (perhaps using the Doteditor)
  • Collapse and expand branches
  • Display a portion of the graph (using Cypher Query Language or Dataview)
  • Hover for node details
  • Preview

Other notes

  • By the way, the plugin for Excalidraw is awesome! I’m still not sure if the Graphviz engine can be embed as a script of it? Here is the roadmap for the Excalidraw plugin
  • Should the plugin be method-oriented (e.g. Graphviz for Obsidian) or goal-oriented (e.g. Hierarchy graph for Obsidian)?
  • Some other products that maybe worth to look at: Kroki, TikZ
  • The Resources page of Graphviz has a lot of resources
  • I must admit that after satisfying my needs, I will have less motivation for it until I meet another occurrence that I need to use the features I haven’t implemented

Any thought is much appreciated.


Version 0


Master graph:

A cluster of the master graph:


  • Auto-wrap node lables to prevent overflow texts

  • Detect different node type whether by it being the end node of a particular edge type, or by the index at the beginning of its title

  • Support default node and edge styles

  • Support subgraphs, and styling for each subgraph

  • Support same rank for each subgraph

  • Support cluster for each subgraph

  • Support pairing nodes (nodes that should be a cluster by themselves)

  • Generate a master graph and individual graphs of each cluster (ideal for large graph)

  • Generate with unflatten (useful to distribute nodes on the same rank of a wide graph to different lines)

To learn how to use the plugin, visit GitHub page.


After having more knowledge about programming and Obsidian, I think there are two ways to make the plugin more stable and easier to expand in the future:

  • Using a template language (e.g.: Handlebars, Eta). I hope that we can even use Templater to build the script
  • Using Graphviz API (which is Python)

As advised by a mod of the Graphviz forum, I should use the API to be less likely to screw up the string-escaping. What would you think about this?

1 Like

This is very exciting - have you been working on this in the background? I still see the utility in this plugin despite the launch of canvas, in which creating hierarchical structure would still very much be a ‘manual’ way of achieving this.

For comparative functionality/future reference, the Argdown plugin makes use of Graphviz under the hood. With some creativity, you are able to generate hierarchical graphs using Argdown notation like so:

[Parent A]
  -> [child 1]
      -> [child 2]

[Parent B]
  -> [child 3]
  -> [child 4]

Play around with the ordering/indentation levels to observe the effects of the underlying dot layout algorithm.

Well, I haven’t been able to work on it since then, but I really want to do that. My idea is to switch from using Breadcrumbs’ API to Dataview’s API, and making it be able to render in codeblock, so that you can embed the graph in notes.

@Jillard also made a similar script Dataview to Mermaid Flowchart, which I also want to make it into a full-fledged plugin. Take a look at those links.

If you want to see the new version soon, not really be fluent in programing and are willing to learn, I can help you with that.

In my understanding Argdown uses viz.js, not Graphviz. And if you use Unicode there is an inconvenient bug with the box padding:

See: Blocks with unicode characters are rendered misaligned · Issue #9 · amdecker/obsidian-argdown-plugin

That’s unfortunate, but based on the original repo, vis.js is a graphViz port.

More on the Argdown graphViz settings here.