Using assorted tools to untangle my Logseq pages and graphs.
- Unify my Logseq setup across macOS and Linux
- Process Logseq notes for analysis
- Clean up inconsistent formatting and properties
- Publish my Logseq notes to My Public Brain
- Translate my Logseq notes to other PKM systems
- (eventually) get all the pieces behaving nicely on Windows
This very initial push is still hard-coded to my particular workflow, and I'm writing this file when I should be finishing up moving prep. There are probably hard-coded aspects for my workflow, so look at the code before you run anything.
Initial code sketches – or "prototypes" if your background isn't in art – are in Python. If performance, portability, or my attention span become an issue, I may port my sketches to Go or Rust.
just runs the tasks.
Processing and analysis are needed at individual, object collection, and full graph level. I use Polars for processing at the collection level. Graph processing is managed with the Kùzu embedded graph database, though I'm still evaluating that particular bit of tooling.
Kùzu's interactive explorer runs as a container, so you'll almost certainly want to have Docker working.
I'm on 3.11 via a .venv managed by uv. Tests are managed with pytest, while Ruff and mypy look for code quality issues. Rich is there to make my console pretty.
These instrutions assume a uv-based workflow. If you're using another set of tools, you'll need to modify for your own workflow.
Create a virtual environment to hold project-specific dependencies.
uv venvInstall those dependencies.
uv pip sync requirements.txtAdding because it's the sort of trivia I'm always forgetting. Check .venv/Scripts for the activate.* script appropriate to your platform. Here's my main ones:
Linux or other UNIX-like with GNU Bash:
source .venv/bin/activateNushell:
overlay use .venv/Scripts/activate.nuSpecify the location of your graph in your shell environment or a .env file.
GRAPH_PATH = "~/my-logseq-brain"To use the kuzu REPL or interactive explorer, install that.
For those macOS and Linux folks using Homebrew:
brew install kuzuTo use Kùzu's interactive explorer, make sure Docker is set up and running on your system. Details on that vary enough that I won't bother breaking it down here.
Write code. Run tests. Run linter and type checks.
just test checkYou can do this with only the Python dependencies installed. You'll have to do all the graph analysis via Python if you stop here though.
just dbThis generates a fresh database in graph_db/, removing any data previously in
place.
Make sure you have the kuzu executable and Docker installed on your system.
just exploreRemember you can combine tasks, so if you want to explore a guaranteed1 fresh database:
just db exploreUsing the MIT License for this.
Copyright 2024 Brian Wisti
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Footnotes
-
this software comes with no guarantees, explicit or implied. Good luck! ↩