Skip to content
Zettel Network Visualizer
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets ENH: Add Screenshot and tags to README (#15) Aug 8, 2019
keyboard-maestro ENH: Add option to use Graphviz to draw the network (#13) Aug 7, 2019
tests CLN: Use Black formatter on codebase (#18) Aug 11, 2019
zkviz REL: v1.3.0 (#19) Aug 11, 2019
.gitignore ENH: Add gitignore for macOS and Python Jun 9, 2019 REL: v1.3.0 (#19) Aug 11, 2019 Add licence file Apr 11, 2019 ENH: Add option to use Graphviz to draw the network (#13) Aug 7, 2019

zkviz: Visualize Link Network Between Zettels (Notes)

Version License

Produce an interactive overview of all your notes and their connections.


I recommend using Python 3 and an environment specifically for zkviz.

Assuming that you're using macOS or Linux, to create the environment, open a Terminal window and type the following to create the standalone environment and activate it.

python3 -m venv ~/envs/zkviz
source ~/envs/zkviz/bin/activate

Then install zkviz with:

pip install zkviz

If Graphviz is installed on your computer, zkviz can use it to draw the network. It is not a Python package so it needs to be installed independently. If you're on a Mac and have Homebrew installed, you can install Graphviz from a Terminal with:

brew install graphviz


To execute zkviz from the Terminal, you either need to add the zkviz environment path to your PATH environment variable or specify the path to the zkviz executable directly. Below, I use the explicit path.

Executing zkviz without any argument will build the visualization based on all the *.md files found in the current directory.


You can also point zkviz to the folder containing your notes. For example:

~/envs/zkviz/bin/zkviz --notes-dir ~/Notes

By default zkviz will look for files with the .md extension, but you can override the default with the --pattern option:

~/envs/zkviz/bin/zkviz --pattern '*.mkdown'

You can also specify multiple patterns separately. With the following, zkviz will find all txt and md files. I recommend wrapping the pattern in quotes.

~/envs/zkviz/bin/zkviz --pattern '*.md' --pattern '*.txt'

You can also pass a list of files to zkviz:

~/envs/zkviz/bin/zkviz "~/Notes/201906021303 the state of" "~/Notes/201901021232 Journey to the center of the"

To use Graphviz to generate the visualization, add the --use-graphviz option:

~/envs/zkviz/bin/zkviz --notes-dir ~/Notes --use-graphviz

By default, zkviz will draw a node for every reference found in the files provided, even if the referenced zettel does not exist, and even if a zettel refers to itself. You can change that behavior in two ways. The --only-list option tells zkviz to draw links only to zettels that have been provided to it. In the example below, only links between the two zettels will be shown:

~/envs/zkviz/bin/zkviz --only-list "20190810190224 Note" "20190810190230 Note"

The other way to change the behavior is to disable self-reference links using the --no-self-ref option.

Using zkviz with Keyboard Maestro

The keyboard-maestro folder includes a Keyboard Maestro macro to automatically create a visualization based on the list of files currently selected in The Archive. To use this macro, download it and import it into Keyboard Maestro. The follow the README comment within the macro to set the necessary variables.

Making a Release

  1. Bump the version in zkviz/
  2. Update the changelog, link the versions.
  3. Commit and tag with version number
  4. Build a source dist with python clean && rm dist/* && python sdist
  5. Test upload to PyPI test with twine upload --repository-url dist/*
  6. Create a temporary environment mktmpenv and test install with pip install --index-url zkviz
  7. If everything looks good, upload for real with twine upload dist/*
You can’t perform that action at this time.