zkviz: Visualize Link Network Between Zettels (Notes)
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
*.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
~/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
~/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
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
Using zkviz with Keyboard Maestro
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
- Bump the version in
- Update the changelog, link the versions.
- Commit and tag with version number
- Build a source dist with
python setup.py clean && rm dist/* && python setup.py sdist
- Test upload to PyPI test with
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
- Create a temporary environment
mktmpenvand test install with
pip install --index-url https://test.pypi.org/simple/ zkviz
- If everything looks good, upload for real with
twine upload dist/*