Nroam - Org-roam backlinks within org-mode buffers

Hi!

I’ve been working on a package named nroam, a supplementary package for org-roam that replaces the backlink side buffer. Instead, it displays org-roam backlinks at the end of org-roam buffers.

The package is quite young, so use it with care (and backup your precious org files).
I’d be really interested in feedback.

Cheers,
Nico

8 Likes

This speaks to me!

I’ve had the same concern and a backlinks section in the document itself indeed seems like an improvement. Haven’t tried it though.

Regarding performance, having optimized the org-id code myself, it is possible to make it fast. But all is relative I suppose. Have you done any profiling?

If its slower than org-id-update-id-locations (from master) then there should be low hanging fruits in the performance department.

No, I haven’t. I will if performance actually becomes a problem :slight_smile:

Okay, tried it out.

Great work! Visually it is much more attractive than having a separate buffer. Also, having this as an add-on kind of leaves us with both options. Perfect :slight_smile:

Some notes on the implementation.

  1. I would personally let nroam--crawl-source just write to a temporary or hidden buffer for the backlink-content instead of opening up each and every file.
  2. It seems the inserted backlinks makes the buffer status become modified. Slightly annoying.

In fact, I did try to change the code for (1) above and it makes the backlinks-section creation near instantaneous. And it won’t create buffers for all the linked references up front either. Not sure if my test is something you’d implement straight of the bat. But you can get the patch if you want to have a look!

1 Like

I have to take this back. Maybe a temporary glitch, seems to work fine now. :+1:

If you’d like to open a PR, I’d be happy to discuss this on GitHub! :slight_smile:

1 Like

I just tried it. I love the idea :-).

I would have used the same function that populates org-roam instead of
rewriting it, calling (run-hooks 'org-roam-buffer-prepare-hook). Why did
you feel the need to rewrite it?

Actually, I do something similar when exporting my braindump
(Devel/KONIX_org-roam-export.el at master · Konubinix/Devel · GitHub),
using org-roam–get-backlinks also, and know I regret since I don’t have
the bibtex integration and ref backlinks.

Anyway, it is a great idea and I definitely will try to use it :-).

1 Like

Unless I’m mistaken, org-roam-buffer-prepare-hook wouldn’t be a great fit for nroam, as the backlinks sections need to be added after saving a file, and removed prior to saving.

Nicolas Petton via Org-roam orgroam@discoursemail.com writes:

Unless I’m mistaken, org-roam-buffer-prepare-hook wouldn’t be a great fit for nroam, as the backlinks sections need to be added after saving a file, and removed prior to saving.

I’m sorry I don’t understand what you mean. As far as I can tell,
nroam–insert-backlinks gets the backlinks from org-roam–get-backlinks
and insert them with the help of the insert emacs function.

By looking at the code of the hooks in org-roam-buffer-prepare-hook, I
see they do exactly the same.

More precisely, nroam–insert-backlinks looks a lot like
org-roam-buffer–insert-backlinks to me.

The good point of being able to reuses the methods that fill the
backlink buffer is that you would take advantage of the bug fixes and
new features.

For instance, currently, org-roam-buffer-prepare-hook contains
org-roam-buffer–insert-title, org-roam-buffer–insert-backlinks and
org-roam-buffer–insert-ref-links. You could drop the
org-roam-buffer–insert-title part as I guess putting the links at the
bottom of the page would need another kind of title. Then you have
org-roam-buffer–insert-backlinks, doing (IIUC) the same as
nroam–insert-backlinks and also org-roam-buffer–insert-ref-links doing
something more than nroam.

You could re implement org-roam-buffer–insert-ref-links in nroam, but I
feel that this is not DRY and you’d need to implement whatever put in
org-roam-buffer-prepare-hook.

Plus, I assume that org-roam-buffer-prepare-hook is meant to be
customized by people or extension to customize the org-roam buffer. It
would be great if that customization would be part of nroam also.

I tried replacing (seq-do #'nroam–insert-backlink-group groups) with
(run-hooks 'org-roam-buffer-prepare-hook) in nroam–insert-backlinks and
I can see the content of the roam buffer instead of the content
generated by nroam. They look a lot alike to me.

2021-02-25T13-59-21-01-00.png

2021-02-25T13-59-48-01-00.png

Sorry if my answers are poorly formatted, I am new in discourse and
using the mailing list mode.

The last part of my message was cut, it was:

Of course, this is not functional as is, because (run-hooks
'org-roam-buffer-prepare-hook) needs to set some things up before being
called, and as you can see, I get the title of the org-roam-buffer as
well as the title of nroam.

But I truly believe it is the « correct » path to take: trying to use
the same mechanism in nroam and org-roam-buffer.

My best, and thanks for the great idea of nroam.

By the looks of it, Nroam avoids the backlink section in the note to be saved to the file. This is done with before-save and after-save hooks. org-roam-buffer-prepare-hook might be able to insert the backlink section, but I don’t think it can be used to remove the section just before save-buffer to avoid the section to be saved in the file. I think that’s what @NicolasPetton is saying.

@konubinix
It seems that you are saying something at a different level, but perhaps it was not clear (not exactly clear to me, at least).

The key difference is in how backlinks are rendered. In nroam the entire subtree get inserted, that’s the reason why I re-implemented it in nroam.

Unless org-roam in the future takes the approach of displaying the entire subtree of each backlink, I disagree.

Consider the following screenshot from nroam:

1 Like

Versus the same backlinks from org-roam:

2021-02-25-183036

nobiot via Org-roam orgroam@discoursemail.com writes:

By the looks of it, Nroam avoids the backlink section in the note to be saved to the file. This is done with before-save and after-save hooks. org-roam-buffer-prepare-hook might be able to insert the backlink section, but I don’t think it can be used to remove the section just before save-buffer to avoid the section to be saved in the file. I think that’s what @NicolasPetton is saying.

@konubinix
It seems that you are saying something at a different level, but perhaps it was not clear (not exactly clear to me, at least).

I agree that there are 2 dimensions in this conversation. Actually, I
can see 3 dimensions.

  1. nroam plays nicely with the saving mechanism to avoid saving the
    added content to the file
  2. nroam generate different content than org-roam
  3. nroam generate the content at the bottom of the buffer instead of in
    a side window

About 1., I did not take a close look at how it does this, but whatever
content you insert, nroam makes sure it won’t be saved.

For instance, I replace (seq-do #'nroam–insert-backlink-group groups)
by (insert “test”) in nroam–insert-backlinks and got “test” inserted
instead of the backlinks. Replacing it with (run-hooks
org-roam-buffer-prepare-hook), it get the content of the org-roam buffer
and still the content is not saved in the file.

About 2. according to the other answer from @NicolasPetton, I understand
that there is a divergence of opinions. While org-roam only show few
information about the backlink, nroam shows the whole subtree.

I understand and respect that decision.

My point is more that I believe that 2 and 3 are independent. I think
that whatever the content generated, some people might prefer to have it
in org-roam buffer and other people in the bottom of the buffer. But I
don’t think that those people might want different content depending on
the use case.

For instance, I like:

  • the way nroam generate the backlinks
  • the fact that org-roam generates ref links
  • the generation of those in the bottom of the buffer

But some people might prefer for instance nroam styled backlinks in the
org-roam buffer.

I don’t see why it would not be technically feasible, even though I
understand the argument that we don’t have time to write the code to do
this.

In conclusion, I think that ideally, nroam and org-roam could have the
same basis to fill the backlink section. I assumed
org-roam-buffer-prepare-hook was a good candidate, but I’m likely to be
wrong.

Using this common basis, one user could decide what content to put in
the backlink section according to their preferences, like (setq
org-roam-buffer-prepare-hook '(nroam-insert-title nroam-insert-backlinks
org-roam-buffer–insert-ref-links)).

Then, the user would decide to put this content in the org-roam buffer
with M-x org-roam or at the bottom of the buffer with M-x nroam-mode.

I hope it is clearer now. Again, I’m just sharing my thoughts and
totally don’t ask for anything.

1 Like