org-z

org-z copied to clipboard

• org-z

#+begin_quote Lightweight, Org-mode flavored zettelkasten links. #+end_quote

org-z is an Emacs global minor mode that enables a lightweight, Org mode style zettelkasten. Unlike a traditional zettelkasten, org-z focuses on headings rather than pages, allowing you to make hyperlinks within a single Org mode document.

By treating headings, rather than pages, as first-class, we can use standard functions that ship with org like [[https://orgmode.org/manual/Handling-Links.html][org-store-link]] to maximum effect.

org-z has the following features:

• Insert links to org headings with interactive search (~C-c-.~ by default). [[https://github.com/emacs-helm/helm][Helm]] and [[https://github.com/raxod502/selectrum][Selectrum]] are supported.
• Links are managed automatically using [[https://orgmode.org/manual/Handling-Links.html][org-store-link]] and org-ids
• Links to new / missing targets auto-create targets in a configurable file location (~new.org~ by default). Creation of the new heading is customizable using a capture template.
• [[./CHANGELOG.org#backlinks][Backlinks]]

#+CAPTION: Inserting a link to an existing heading #+NAME: existing-heading [[./images/org-z-existing-heading.gif]]

#+CAPTION: Inserting a link to a new heading #+NAME: new-heading [[./images/org-z-new-heading.gif]]

** Installation

Install with straight.el:

#+begin_src emacs-lisp (use-package org-z :straight (org-z :type git :host github :repo "landakram/org-z") :config (org-z-mode 1)) #+end_src

org-z requires a completion backend. [[https://github.com/emacs-helm/helm][Helm]] and [[https://github.com/raxod502/selectrum][Selectrum]] are currently supported. You'll need to load one of the completion backend packages, in addition to org-z itself:

#+begin_src emacs-lisp (use-package org-z-selectrum :straight (org-z-selectrum :type git :host github :repo "landakram/org-z")) #+end_src

Loading the package sets the completion backend by appending to ~org-z-completion-backends~ and setting ~org-z-completion-backend~.

** A lightweight zettelkasten

I combine org-z with a daily journal, implemented as a ~file+datetree~ capture template, and [[./CHANGELOG.org#backlinks][org-z's support for backlinks]].

#+begin_src emacs-lisp (setq org-capture-templates '(;; ... ("j" "Journal entry" entry (file+datetree "~/org/journal.org") "* %?\n" :unnarrowed t)))

(use-package org :straight org-plus-contrib :config (require 'org-eldoc))

(use-package org-z :straight (org-z :type git :host github :repo "landakram/org-z") :general (leader-def :infix "o" "b" 'org-z-backlinks-at-point) :config (org-z-mode 1)) #+end_src

As I go about my day, I make journal entries that link to various headings in my collection of org files. I make these links by invoking ~org-z-insert-link~ as I write my journal entry. I periodically inspect backlinks using ~org-z-backlinks-at-point~ to investigate connections. By enabling ~org-eldoc~, I get to see the # of backlinks for a given heading when I hover over it.

Every once in a while, I review my journal entries and ~org-refile~ headings or simply re-organize journal entry knowledge into "longer-term storage" (~reference.org~ or ~projects.org~).

** Motivation

I was inspired by [[https://github.com/org-roam/org-roam][org-roam]], but wanted something that fit my existing org workflow, which is a handful of files with deep headings rather than a file per topic.