Sharing experience from building V2 compatible extension: Md-roam for v2 (not compatible with the latest commit yet; I’ll need to fix it for the latest DB schema).
@zaeph , you can take this as feedback from one of the first penguins
It is relatively easy if your implementation is done to be compatible with Org-roam in the following way (I try to be exhaustive based on what I have seen, but I’m writing this at my lunch time. Apologies if I miss important elements).
If you want to re-use what Org-roam offers as much as you can, I would assume you wanted to use
backlink-section in the Org-roam buffer. To do this:
- Both source and target are text files with a file extension and are located in
- Both source and target are recognized by
Let me explain.
1. File and extension
Org-roam looks only at files within
org-roam-directory, and it checks if a given file is an Org-roam file. It does so by checking each file’s extension defined in user option
org-roam-file-extensions (inspect the function
org-roam--org-file-p). The user option is a list so it can be more than one (In my case, I need to add
org in the list).
For the idea of the email or Git branch to work, with the current Org-roam implementation, an email or Git branch would need to be stored as a file within
org-roam-directory. You could use symbolic link, so the location might not be an issue; however, I am not sure if emails and Git branches are stored as files with an extension. If not, you would need tweak this part of Org-roam, probably in rather significant a way.
2. Nodes and
V2 looks at nodes only. This means both source and target files need to be nodes.
For your idea of an email, as an example, you open an email file, and it needs to be a node as well as the Org-files to be displayed as backlinks. Technically, you can inspect the function
org-roam-buffer. It immediately checks if the current buffer (a buffer for an email, for example) is a node with
org-roam-node-at-point; if the point is not on an org-id, it first looks for the next org headline and then to the beginning of the buffer to check for the file’s ID.
Thus… you can see that the current implementation has a specific definition of nodes: nodes are Org headlines or files recognized by Org-ID and only Org-ID. Org-ID does not care about the file extension, but (I believe) the file needs to be a text file (not a binary) and conform to the Org syntax to define a file or headline ID (within a property drawer).
In my case, I advise an Org-ID function so that an ID within YAML frontmatter can be recognized as an Org-ID, thus an Markdown file can be a node within Org-roam.
Emails might be OK (aren’t they stored as text files?). For text files with different syntax, advising works like I did for Markdown files. But I’m not sure of Git branches and commits (are they somehow compressed binary to reduce the size?)
EDIT: One last thing before I forget. If you go down the path of adding a file to the database, note how
org-roam-db-update-file is implemented. It uses
org-roam-with-file macro, which turns off the major mode and on
org-mode – this took me some time to debug and understand. This does not fit in the two points above and implementation detail, but could save you some time.