zkviz: Visualize Link Network Between Roam Research Notes

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

This fork adds support for the file format and page [[linking]] of Roam Research notes export. Assumes wikilink markdown formatting. Nested [[[[Titles]]]] are not supported (yet), as well as hashtags and attributes.

Installing

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.

Clone this repository

Install this fork with:

python setup.py install

Run with

python ./zkviz/build/lib/zkviz/zkviz.py ./roam-export/*.md

Open the HTML file when complete. Rendering might take a while if your notes directory is large.

The rest of the readme uses the pip package in a virtual environment.

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

Usage

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.

~/envs/zkviz/bin/zkviz

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 affairs.md" "~/Notes/201901021232 Journey to the center of the earth.md"

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 1.md" "20190810190230 Note 2.md"

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/__init__.py
2. Update the changelog, link the versions.
3. Commit and tag with version number
4. Build a source dist with python setup.py clean && rm dist/* && python setup.py sdist
5. Test upload to PyPI test with twine upload --repository-url https://test.pypi.org/legacy/ dist/*
6. Create a temporary environment mktmpenv and test install with pip install --index-url https://test.pypi.org/simple/ zkviz
7. If everything looks good, upload for real with twine upload dist/*