Zettelkasten Forum

Visualising Links between Zettels with Keyboard Maestro and Graphviz

edited August 2019 in Software & Gadgets

Dear Zettelkasten-Community,

I have been wanting to visualise the links between selected notes in my zettelkasten for quite a while, mainly in order to simplify "tidying up" or organising a network of zettels (adding appropriate links, consolidating similar zettels, adding or removing tags from zettels appropriately, etc.).

I was quite involved in this discussion about visualising zettel-networks and followed and tested @alexchabot's work on zkviz, but still didn't find all my needs met – I had the desire to customise the setup a bit more ;) Last week I then decided to try to create my own visualisation-setup, using Graphviz and Keyboard Maestro, which both had a key role in the above mentioned discussions and projects. I wanted to try not to use Python or similar scripting languages in addition to Graphviz and Keyboard Maestro in order to make it easier to customise things for people who aren't familiar with those languages (me included).

What I came up with is a KM macro that is supposed to be triggered when the desired zettels are selected in The Archive, it will finish by opening a .svg-file with the visualisation in Safari.

As with @alexchabot's zkviz, the macro will assume that all zettel titles will start with the 12-digit UID and then have a verbal title. If your titles look different, the macro won't work. The macro also assumes that all your notes have the extension .md.

Given all this, the following steps need to be done in order to get it running:

  1. Graphviz needs to be installed. If you have Homebrew, run brew install graphviz in the Terminal.
  2. In order for the graphviz command dot to be found by the Keyboard Maestro engine, the folder that Graphviz was installed in needs to be added to the folders that KM searches for shell-commands. This can be done by adding the variable ENV_PATH under Keyboard Maestro's "Preferences -> Variables" and setting it to /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin (the folder /usr/local/bin was previously not searched).
  3. Download the main KM macro under this link, open it in KM and change the entries that I marked in the following image according to your needs (5 pathnames):
  4. Download this additional KM macro that generates a list of the notes in your zettelkasten from time to time. This list is needed in order for the main macro to work and can also be used for many other purposes (which is why I keep it separate). Adjust your zettelkasten-folder if necessary.
  5. If your notes all have the same extension, but not .md, you can easily change the extension in the relevant macro (to e.g. .txt). If your notes have several different extensions, it's not straightforward to make it work (at least from my perspective), but it should be possible.

That's pretty much it. The output for a small group of my zettels looks like this:

  • If you create your own .svg-files with the macro, the nodes are clickable and will lead to the corresponding note in The Archive (URL-scheme).
  • All the selected notes are in the darker blue, non-selected notes that they link to are shown in a light blue (if desired). The colours can easily be changed in the macro.
  • You can also try other programs than dot included in the Graphviz package by changing the command dot in the "Execute Shell Script" action (not the file extension .dot which can be used by all the programs!) to neato, circo, fdp, sfdp or osage– they will all result in different arrangements of the nodes. Play around and see what you like best.
  • You can also play around with different node shapes, arrows, nodelines, etc. – look at what the DOT-language has to offer, e.g. here.

Looking forward to feedback and images!

And thanks to @alexchabot and Tom in the KM-forum for your ideas and help!

Post edited by ctietze on


  • That's awesome! Well done @Vinho!

  • edited September 2019

    Thanks @alexchabot! Glad you like it. And again: without you I wouldn't have done it ;)

    The only thing I'm not happy with is Safari asking for permission to open the note in The Archive every single time I click on a node. But apparently nothing can be done about except for changing the browser...

  • @Vinho great work. Those people on the Keyboard Maestro forum are super!

    1. ggrep is not in the default macOS. Installed via brew install grep. (Homebrew also must be installed.)
    2. ~/Dropbox/zettelkasten/-visualisation/zkselection.dot is not automatically created.
    3. Importance of helper script that generates a list of the notes could be more prominently stressed.

    1. I see where 'Safari' is defined as the browser. Changing this to 'Chrome' throws an error. Any idea of the naming convention required?

    Will Simpson
    I must keep doing my best even though I'm a failure. My peak cognition is behind me. One day soon I will read my last book, write my last note, eat my last meal, and kiss my sweetie for the last time.

  • edited September 2019


    Thanks for the feedback!

    1. Thanks for pointing out the fact about ggrep, I forgot that was in there.
    2. I think the file zkselection.dot is automatically created (the action "Write to File" will recreate it if I manually delete it), but presumably the folders mentioned in its path need to exist in order for that to work.
    3. Hm, I had hoped it was stressed enough (step 4 of the steps I mentioned in my post). Unfortunately, I can't edit the post anymore to change anything...

    4. I think you have to refer to Chrome as 'Google Chrome'. Does that work? Personally, I don't have it installed, so can't test it.

  • @Vinho
    Still experimenting with this view of the note relationships. Have you a way to get more than one level deep? It would be interesting to select a single note and see second-order linking. This might lead to something surprising.

    Yes, referring to Chrome as 'Google Chrome' does that work.

    When selecting links in the zkselection.svg I got this dialog, once then no more.

    Will Simpson
    I must keep doing my best even though I'm a failure. My peak cognition is behind me. One day soon I will read my last book, write my last note, eat my last meal, and kiss my sweetie for the last time.

  • @Will: That's sounds similar to what I wanted here. I created a KM Macro to visualise children hierarchies with Graphviz first, but then realised that specifically the outline view in OmniOutliner is much more helpful for me... Let me know what you think.

    Did the dialog you posted above appear in Safari or did you use Chrome?

  • @Vinho
    Sorry to not make it clear about the dialog. It appeared in Chrome. Unlike the one activated in Safari, it allows an "Aways open these type of links in the associated app".

    Will Simpson
    I must keep doing my best even though I'm a failure. My peak cognition is behind me. One day soon I will read my last book, write my last note, eat my last meal, and kiss my sweetie for the last time.

  • @Will: Yes, I thought so. It's a shame that Safari doesn't offer that option.

  • This is fantastic script, thanks so much for sharing.

    I had an issue with ggrep not executing in background mode, and used the solution found here:

    For me it was just referencing the full path from "which ggrep":
    ls | /usr/local/bin/ggrep -P '[0-9]{12}.+' | cut -d'.' -f1

  • edited October 2019


    It's a pleasure – I'm glad you find it useful!
    Thanks for letting us know about your problem with ggrep and your solution.

Sign In or Register to comment.