denote-tree

denote-tree is a simple utility, that allows you to see and move within tree structure of your notes with standard GNU Emacs movement keys. Because of how it operates, stuff like setting a mark just works without reimplementing them.

Usage

Just clone this very repository, add it to your load path and enable the package:

(add-to-list 'load-path "~/path/to/repo")
(require 'denote-tree)
;; optionally one can add denote-tree-link
;; (require 'denote-tree-link)

If you have GNU Emacs>=29.1, then feel free to get it from here:

(package-vc-install
 '(denote-tree
   :url "https://github.com/sarcom-sar/denote-tree"
   :vc-backend Git))

The entry point function is denote-tree, which acts on any file-visiting buffer (defaulting to the current buffer) searching for any denote identifiers within it.

It is able to handle cyclical notes and provides a mechanism to move between those cyclical nodes by default. The initial cost of drawing a full tree is paid once, at initialization. If user is willing to do so, one can tweak the value of denote-tree-max-traversal-depth, so that the tree is drawn only partially. That truncated tree can be then expanded via denote-tree-redraw.

The extension denote-tree-link is provided if the user wishes to additionally link, unlink and create new nodes. They are not defined in denote-tree-mode-map, but they can be added like so,

(dolist (el '(("i" . #'denote-tree-link-nodes)
              ("u" . #'denote-tree-unlink-node)
              ("s" . #'denote-tree-spawn-child-node)))
  (keymap-set denote-tree-mode-map (car el) (cdr el)))

Keybindings for *denote-tree* buffer

Keybinding	Function
n	denote-tree-next-node
p	denote-tree-prev-node
f	denote-tree-child-node
b	denote-tree-parent-node
g	denote-tree-redraw
e	denote-tree-edit-node
w	denote-tree-copy-node-id
RET	denote-tree-enter-node

Visualization

'-* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  +-* Phasellus at dui in ligula mollis ultricies.
  | '-* Nullam libero mauris, consequat quis, varius et, dictum id, arcu.
  |   '-* Nulla posuere.
  +-* Nunc aliquet, augue nec adipiscing interdum,
  | '-* Donec vitae dolor.
  '-* Proin quam nisl, tincidunt et, mattis eget, convallis nec, purus.
  | +-* Nam euismod tellus id erat.
  | '-* Donec pretium posuere tellus.
  |   '-* Nullam libero mauris, consequat quis, varius et, dictum id, arcu.
  +-* Vestibulum convallis, lorem a tempus semper.
  '-* Dui dui euismod elit, vitae placerat urna tortor vitae lacus.

Documentation

Customizable elements

• denote-tree-preserve-teleports-p, teleport back when accessing cyclical node from it’s child. When nil, always move to “real” parent of a node.
• denote-tree-node-description, elements of front matter to include in node’s description. User can also extend denote’s front matter by any arbitrary element, but they have to add corresponding regex and type to denote-tree-extend-filetype-with in order for denote-tree to recognize it. That user variable also supports arbitrary strings. Denote’s default front matter elements: title, identifier, keywords, signature, date, symbol or arbitrary string.
• denote-tree-max-traversal-depth, maximum traversal depth of denote-tree. If t traverse all the way, if num, traverse n nodes deep. If user feels that deeper probe is necessary, then the depth of a node can be extended with denote-tree-redraw.
• denote-tree-title-colorize-function, Add properties to information from the node according to type. Function accepts two arguments STR and TYPE. Choosen string from front-matter is propertized according to type from denote-tree-node-description.
• denote-tree-buffer-prefix, every denote tree is built by a custom custom prefix, customizable here, and root node of a tree.
• denote-tree-extend-filetype-with, extend what kinds of regexps denote-tree is aware of in your front matter. It also provides backwards compatibility with versions od denote older than commit 3517ba2.

denote-tree-link

• denote-tree-link-insert-function, return the region at which the link is to be inserted. The function takes no arguments and returns a pair of intergers. The range determines a buffer region in which text will be replace with a link. If the pair is the same integer, then perform the insertion in place.
  • denote-tree-insert-at-eof, return a pair of locations at the end of the file.
  • denote-tree-insert-after-front-matter, return a pair of locations after the front-matter, if it fails default to denote-tree-insert-at-eof.
• denote-tree-link-after-link-insertion-hooks, List of hooks to run after the link was inserted. This variable is primarily used to modify the text around inserted link. Before this hook is ran the buffer is narrowed to just the link itself.

Faces

• denote-tree-circular-node, default face used for circular nodes.
• denote-tree-node, default face used for nodes.

User facing functions

• denote-tree (&optional buffer) Draw hierarchy between denote files as a tree. The function allows the user to choose between all file-visiting buffers. If called non-interactively, then the BUFFER has to be a valid denote-style identifier.
• denote-tree-next-node (&optional arg) Move the point to the next sibling node ARG times. If ARG is negative move to the prev sibling node ARG times. If ARG is omitted, nil or zero, move once.
• denote-tree-prev-node (&optional arg) Move the point to the prev sibling node ARG times. If ARG is negative move to the nextv sibling node ARG times. If ARG is omitted, nil or zero, move once.
• denote-tree-parent-node (&optional arg) Move the point to the parent of a node ARG times. If ARG is negative move to the child of a node ARG times. If ARG is ommited, nil or zero, move once. If denote-tree-preserve-teleports-p is set to t, teleport to the parent the point came from.
• denote-tree-child-node (&optional arg) Move the point to the child of a node ARG times. If ARG is negative move to the parent of a node ARG times. If ARG is ommited, nil or zero, move once. With universal-argument reverse denote-tree-preserve-teleports-p one time. If denote-tree-preserve-teleports-p is set to t, preserve the parent node position for future backtracking.
• denote-tree-redraw (&optional arg) Redraw some part of a tree. Without C-u, redraw the current node deepening it. With C-u draw current node in a new window. With C-u C-u, redraw the entire tree.”
• denote-tree-edit-node () Edit current note via denote’s denote-rename-file.
• denote-rename-copy-node-id () Save canonical denote id to the kill ring.
• denote-tree-enter-node (&optional button) Enter node at point in other window. BUTTON is pased as node’s ID.

denote-tree-link

• denote-tree-link-nodes (from-mark to-point) Link node at FROM-MARK to TO-POINT. If denote-tree-link-insert-function is set, then perform this based on function’s return value. Otherwise open a TO-POINT file and let the user decide where in TO-POINT node the link to FROM-MARK should be set.
  • denote-tree-link-finalize (&optional stay-with-capture) Insert a link between point and mark in the note buffer. With prefix argument STAY-WITH-CAPTURE, jump to the location of the captured item after finalizing.
  • denote-tree-link-kill () Abort the linking, restore window configuration. Do not actually kill the buffer itself, since the user might wish to examine it.
• denote-tree-link-unlink-node (pos) Unlink the node at POS from it’s parent. Leave only the text that was there before the linking. If the link contains only an ID, delete entire line sans the newline.

Contributing

As usual, contributions are always welcome. Feel free to open an issue on the issue tracker, if you find a bug, have an idea, etc. Same with code contributions.

To-Do list

• [X] Make it major mode agnostic;
• [X] give the user the ability to colorize node titles;
• [X] unite traversal functions;
• [-] smarter redrawing of a tree,
  • [ ] collapsible tree (with hierarchy.el);
  • [X] redraw parts of a buffer,
    • [X] works while linking nodes;
    • [X] works while unlinking nodes;
    • [X] move unlinked node to one of cyclical nodes who is still linked.
• [X] ability to edit the front matter at point;
• [ ] edit front matter with widgets;
• [X] multiple denote-tree buffers;
• [X] notes interaction,
  • [X] link two notes;
  • [X] unlink a note.
  • [X] create a note linked to other note;