notice: im currently still writing the readme so it is incomplete.

the “mandatory gif” demo:

this is the simplest possible usage, alot more is possible as custom patterns can be defined for any filetype and blk would take care of the abstract task of linking and navigating the different patterns with the defined ids/titles.

blk is a very customizable, small package for interlinking arbitrary blocks of text, focused on org mode. as unoriginal and redundant as that may sound, this package doesnt do anything fancy and doesnt try to be anything but a glorified grepper. read on and you shall see how simple yet powerful the philosophy behind this package can be.

the idea behind blk is that “grepping” should suffice for most note-taking and text-interlinking related tasks, and anything more sophisticated would introduce complications that make customizability a harder task for users. the main motive for writing this package was my growing frustration with the current state of note-taking packages like org-roam (it is a great package, this is not to downplay its usefulness and in no way meant as an offense to the people who worked on it, as i feel nothing but appreciation towards the emacs community as a whole), which was of all the most painful to tame to fit a workflow that made sense to me, i considered other alternatives like denote and hyperbole, but i then settled for a small collection of utility functions which was more than enough and far more extensible than those other alternatives, i eventually decided to put this functionality into a package for it could be useful to others aswell.

this package doesnt try to introduce any new syntax or restrictions, it merely builds on whats available and tries to be integrable with other available packages or standards. so as to avoid being just another equivalent choice in the long list of available note-taking packages.

basic installation with the basic features

(use-package blk
  :ensure ( :host github :repo "mahmoodsheikh36/blk") ;; replace with :straight or :quelpa, etc
  :after (org)
  :config
  (setq blk-directories
        (list (expand-file-name "~/notes")
              (file-name-parent-directory (expand-file-name user-init-file))))
  (blk-configure-org-link) ;; required for blk-open-at-point to work
  (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 f") #'blk-insert))

basic installation with org-transclusion “integration”

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

(use-package blk
  :ensure ( :host github :repo "mahmoodsheikh36/blk") ;; replace with :straight or :quelpa, etc
  :after (org org-transclusion)
  :config
  (setq blk-directories
        (list (expand-file-name "~/notes")
              (file-name-parent-directory (expand-file-name user-init-file))))
  (blk-configure-org-link)
  (blk-configure-org-transclusion)
  (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 f") #'blk-insert))

say you have the following block in file1.org:

#+begin_definition :title definition of a set :name def-set
a set is defined to be an arbitrary collection of items
#+end_definition

first, since the block has a :title property it will be listed in the completing-read interface of blk-find and could be navigated to using its title (like org-roam-node-open except blk supports not only files or headers but also blocks and other patterns of text)

now say you have another file file2.tex:

this is an example of a set:
\begin{equation}\label{set-example1}
  x = \{10, \emptyset, \{1\}, 3\}
\end{equation}

and then in another file code.el what you could do is:

(defun generate-set ()
  "refer to blk:def-set and blk:set-example1"
  (list 10 20))

if you have org-transclusion enabled, you can also transclude the pattern the link is defined to link to, e.g. in another file file3.org you can do

#+transclude: blk:def-set

this will cause the definition block from file1.org to be “transcluded” (inserted) into the buffer of file3.org when org-transclusion-add-all is executed (happens automatically when an org file is opened).

the text to be transcluded for a specific link is defined by the pattern in blk-rg-patterns (or blk-grep-patterns, blk-emacs-patterns, etc, if you decide to use another grepper)

the greppers available for use are currently the standard grep or ripgrep (rg), or emacs itself, only use emacs as the grepper if you really are trying to avoid the dependency of an external grepper as it is an order of magnitude slower than the other options, though it is good to note that the plus side of using emacs as the grepper is that it is aware of unsaved changes to buffers since it greps those instead of the files themselves when they’re already opened in buffers.

for each grepper a different table of patterns is defined, the grepper is chosen by setting the variable blk-grepper and defaults to rg and falls back to grep if rg isnt installed, and falls back to using emacs if grep isnt found aswell.

• blk-grepper-rg <-> blk-rg-patterns
• blk-grepper-grep <-> blk-grep-patterns
• blk-grepper-emacs <-> blk-emacs-patterns

denote can be easily used with blk as their features dont overlap, i myself use denote as a tool to keep my org files names in sync with the in-buffer org settings and blk to insert/open/navigate links and blocks of text.