Documenting to Share a Solution
I’ve been dabbling with the org-transclusion package. But I encountered an odd behavior somewhere in my org-mode and org-roam configuration.
What Worked and What Didn’t
I had a source org file. I linked to the target org file in another directory via the target’s id
property.
In my source I had the equivalent of [[id:org-id-get-create][Name of Target]]
. The org-id-get-create
is a placeholder (and the name of the function I used to generate the target’s ID).
When I would open the target link in my buffer, I would jump to the target document. As expected.
However, when I attempted to use the org-transclusion
functions or export (via org-export-dispatch
) the org document to another format, I got the following error:
Unable to resolve link: org-id-get-create
I thought this had something to do with my directory structure. But it worked to link to other files in the same directory as the target.
Poking Around Through Source Code
I tried rebuilding my org-roam database (e.g., M-x org-roam-db-clear-all
then M-x org-roam-db-sync
) but that didn’t work.
In the source file, I ran org-lint
. That generated reported what looked to be the same error message.
So I dug further into the org-lint
method. There I learned about the org-lint--checkers
variable.
The registered functions that are called to lint a document.
I went looking through that list and found a likely culprit: org-lint-invalid-id-link
.
The org-lint-invalid-id-link
function lead me to the org-id-find
function. Which in turn called org-id-find-id-file id
. And there I found the following code bit of code: (unless org-id-locations (org-id-locations-load))
.
Huzzah! Org-mode was generating a cache! Somewhere there must be a cache invalidation or update function.
So I went looking for functions like the org-id-locations-load
. I found org-id-update-id-locations
and org-roam-update-org-id-locations
.
I ran the org-id-update-id-locations
and it reported processing several files, but certainly not enough. I thenorg-roam-update-org-id-locations
; that function call reported a lot of processed files.
Hoping that this update of a cache would resolve my problem, I went back to the previously broken source document. Both org-transclusion
and org-export-dispatch
worked.
Capturing the Knowledge
I wrote a function that is now part of Emacs configuration; the purpose of the function is to help remind me how to fix this problem if it shows up again.
;; I encountered the following message when attempting
;; to export data:
;;
;; "org-export-data: Unable to resolve link: FILE-ID"
(defun jnf/force-org-rebuild-cache ()
"Rebuild the `org-mode' and `org-roam' cache."
(interactive)
(org-id-update-id-locations)
;; Note: you may need `org-roam-db-clear-all'
;; followed by `org-roam-db-sync'
(org-roam-db-sync)
(org-roam-update-org-id-locations))
I don’t envision running that function all that much, but it will be a bit of written memory of this debugging.
Conclusion
First, navigating Emacs functions is amazing. Emacs provides powerful introspection.
I used helpful.el to jump to the documentation of a function, and kept jumping deeper. I used M-x
paired with marginalia.el to look for similar named functions.
Pairing helpful.el
and marginalia.el
(and many other packages), I could do ever narrowing work and when I needed to expand my focus.
In fact, it was so easy to navigate I did it twice. First when debugging and then when writing this blog post.
Second, taking the time to write this up, I hope I help other folks (including my future self).
Top comments (0)