blk

more documentation may be found at https://mahmoodsh36.github.io/blk.html

introduction

blk tries to generalize the idea of creating and navigating titles of text files, as well as making links from one file to another, or one block to another (possibly in different files). if you have used org-roam, denote, or other similar tools like obsidian and logseq, you would know that inserting links between two files (or nodes, as they’re usually called) and navigating them is a must-have feature for note-taking, with blk, instead of restricting links to specific elements of text, such as a file or a heading, we can insert links to arbitrary forms of text, be it links to an org heading (or markdown heading), or a code block in an org file, or even links to python functions, elisp functions, or an html element (by its id).

installation & basic configuration

basic installation with the basic features

(use-package blk
  :straight (blk :host github :repo "mahmoodsh36/blk") ;; replace with :quelpa if needed
  :after (org)
  :config
  (setq blk-directories
        (list (expand-file-name "~/notes")
              user-emacs-directory))
  (add-hook 'org-mode-hook #'blk-enable-completion)
  (setq blk-use-cache t) ;; makes completion faster
  (global-set-key (kbd "C-c o") #'blk-open-at-point)
  (global-set-key (kbd "C-c f") #'blk-find)
  (global-set-key (kbd "C-c i") #'blk-insert))

basic installation with org-transclusion “integration”

(use-package org-transclusion
  :config
  (add-hook 'org-mode-hook #'org-transclusion-mode))

(use-package blk
  :straight (blk :host github :repo "mahmoodsh36/blk") ;; replace with :quelpa if needed
  :after (org org-transclusion)
  :config
  (setq blk-directories
        (list (expand-file-name "~/notes")
              user-emacs-directory))
  (add-hook 'org-mode-hook #'blk-enable-completion)
  (blk-configure-org-transclusion)
  (setq blk-use-cache t) ;; makes completion faster
  (global-set-key (kbd "C-c o") #'blk-open-at-point)
  (global-set-key (kbd "C-c f") #'blk-find)
  (global-set-key (kbd "C-c i") #'blk-insert))

blk vs interactive grepping

if something like consult-grep is enough for you, and you dont need to make links to specific locations in your files or notes, then this package isnt for you, what it does is that it takes the idea of writing links to other files and extends it to more than just files, it allows for making links to arbitrary blocks of text and transcluding them from one file into another, the transclusion part is to avoid copying for example one equation from an org file into another, you can simply transclude it by its id, this reduces work and keeps the equation in the different files in sync (when the source is edited). note that org-transclusion on its own can handle blocks of text, but you would have to write the filename explicitly, specify what to search for in the file, and what exactly to transclude, blk abstracts this hassle away and allows for unambiguous transclusions (as long as the destination’s id is unique).

todo

rules for file names without needing to grep them (similar to what denote does)

add support for customize (customization via the default interface, i.e. without code)