Package release: Org-Roam-UI

Kirill Rogovoy and I just released v0 of Org-Roam-UI: a replacement for org-roam-server for V2.

We plan to do a whole lot more than just create a fancy graph, and we’d love to hear your thoughts about what the next step should be!

Check out the package and join the discussions at GitHub - org-roam/org-roam-ui: A graphical fronted for exploring your org-roam Zettelkasten


Awesome work! Big thanks to authors! I was jealous about Obsidian users having such a nice graph … until today :smile:

Now I need to find some elegant way how to map a command (browse-url ???) to open browser at with keyboard shortcut.

Just never close it! :rofl:

1 Like

@jethro should it be mentioned in Org-roam User Manual?

1 Like

Is it planned to reflect somehow the in-file nodal org bullets hierarchy (parent<->child) in the graph?

By that I mean the org-roam v2’s ability to have multiple nodes (headings with ID) within one file. If some get nested under other heading, could this be displayed as link to parent heading? Right now all nodes within file link to the file ID node, no matter where the heading/node stands in hierarchy. It’s clear to me that this linkage is not based on direct ID links and that it’s tricky to decide in which direction should such link be connected without explicit definition (parent > child or child > parent) - maybe a possible setting in graph options?

I have a feeling this was asked/discussed before but I can’t seem to find that question so sorry if this is already answered.


The implicit heading-node → file-node link was added as a quick way to fix the majority of simple cases e.g. “daily” files.

I’m not sure at the moment if we will implement something more sophisticated. One of the reasons to not do it would be that working with hierarchies goes a little bit against the philosophy of Zettelkasten/org-roam.

My current impression is that most people try to stick to rather structure-less nodes, but I might be wrong.

All that said, I don’t mind having that behavior behind a toggle that’s off by default, so feel free to make PRs. :slight_smile:

1 Like

Great work, works very fast.

How are the colours determined? Do you use community detection?

It’s mostly based on the number of linked nodes.

It doesn’t make much sense right now: we just wanted to have a colorful graph with some deterministic algo. I think it will change completely over time.

We are going to add more fancy coloring algorithms later, probably based on Tecosaur’s post here


So it is the degree of the vertex. Lots of exiting developments.Keep up the good work.


I’ve seen some users create sort of ‘navigation’ hierarchy which IMHO can be useful.

For example having file node “Journal” with first level heading node “2021” with org sub-heading nodes for months (2021-01 January, 2021-02 February, …) and then link daily file nodes to these sub-headings. Basicaly using heading nodes as a skeleton for links.

As of now all heading nodes in “Journal” file are linked to “Journal” while my org brain expects them to follow the org heading hierarchy.

I’m missing the point then what benefit v2 file-independent org heading node feature brings if sub-heading leveling is irrelevant for linkage. In that case it’s better to stick to file per node structure and use only first level headings where it makes sense which seems kinda limiting and against org-mode principle (subjective opinion, I know :wink: )

In any way, it would be neat to have a switch that enables “Follow org heading node hierarchy” or similar. I believe it would find it’s users.

Edit1: Added an image to show the current behavior.
Edit2: Doubled “2021-08 August” is caused by strange behavior of org-roam when inserting a node into heading - it creates ID on current heading + separate file node with the same title and inserts the link to it.

This is an interesting feature! I don’t per se think that not having nested links invalidates Org-Roam v2’s design: not every heading needs to be a note, so if you have 6 headings of which only one is a note (as well as the parent note) it could still work (I do this).

Finding the next heading node is a bit more of a pain, especially if you want it to (for instance) skip any heading that are not nodes, e.g.

  • Heading 1 :node
    ** Heading 2
    *** Heading 3 :another_node

I think that if you have this linking to higher up nodes, you would want 3 to to link to 1, right?
Anyway, this should not be impossible, the trouble is that this parent structure is not encoded in org-roam, so we have to derive it ourselves. The only relevant info we have is the level of the node and its position, which would allow us to find the parent node.

If anyone else could chime in with “I want this too please” it would speed us up getting to it, for now I’ll add it to the wishlist! (Note: keep a wishlist)

One important point that @ThomasFKJorna touched on is that adding those implicit links between file and heading nodes is done completely org-roam-ui-side. While arguably such features should be a part of org-roam itself.

We made it because it made sense for us at the moment, but making that feature overall larger is a concern because maybe it doesn’t belong to the project at all. :slight_smile:

I totally agree that the links between heading nodes should be ideally somehow reflected in org-roam in the first place for such specific use case so you don’t have to construct anything artificial above it. And it’s true that situations like skipped headings (without ID) are of question how to handle these. Yes, I’d say that in Thomases example above would be the lower node linked to the nearest parent node, so 3 to 1.
But feel free to ignore my ideas :wink: I’m just starting with more or less blank slate of org-roam v2 and trying to wrap my head around all the possibilities, finding the right approach to given tools.
Nontheless, I’m very happy for ideas exchange with more skilled end experienced guys :slight_smile:

@cube48, yes, it does seem that graphs should consider headline hierarchy, and that this was one of the goals of v2. It also seems that if a file is itself a graph node, then headlines should be under it.

Ahh … that’s probably where my expectation stems from :smiley:

I’ve become more convinced that this makes sense to add, although I’m not so sure whether org-roam should implement this itself, main reason being: where would the link be? What kind of link would it be? Would it show up in the backlinks buffer?

Given what is saved in the DB (title, position, olp) we can actually derive hierarchical links from the DB, see WIP: Infer the implied links represented in the org-mode hierarchy. by blester125 · Pull Request #53 · org-roam/org-

The problem is that this involves multiple self joins on the node table, which I would think will get rather large for most users and could result in slow downs. Adding more indexes to the DB could help, but it looks like the LIKE query to find nodes from the olp would never use the INDEX (the right hand side is not a string literal The SQLite Query Optimizer Overview). It is also a complex query that could be hard to maintain. Plus, UIs like org-roam-ui where the whole graph is sent each time need to either pay this cost each time or get a lot more complex by supporting graph updates via diffs.

If org-roam managed saving these links (with a different link type?) in the DB it would make any graphing effort a lot easier, even if org-roam just ignored them. It seems like org-roam, which has access to the actual file would make storing these hierarchy links a lot easier. I guess the trade off is should org-roam store/create this data that it will probably never need/use or should it be derived by those actually using at the cost of having to make sure it is optimized.

great point, @cube48. I’d also expect the hierarchy to be reflected in the graph (a tree graph). While it isn’t a major issue (for me) if outline depth in org-roam files is small, as in your example, making the graph consistent with the header hierarchy would be a great feature. For example, it could instantly enable meaningful graph views of classical org files, simply by giving them a file-level ID and including them in org-roam-directory.

Your point also makes me wonder how org-roam-ui handles a link from one (sub)header in File A to another (sub)header in File B. I would hope that this appears as a direct link on the graph between the two (sub)header-nodes and does not show any links to/from the file-nodes.

Side note, and potentially easier than some of the above topics: I’d like to suggest styling hierarchical links differently from “regular” cross-file links. It would help to distinguish them. For example, dashed, squiggly, etc.

A separate suggestion (this one purely frivolous and just for its coolness factor): file-nodes with hierarchical links to children could have a plus/minus sign on them. Clicking on the file-node turns the plus sign into a minus as the hierarchical links pop out. Click on a node with minus sign to collapse the hierarchical links. In collapsed form, all links going into(/out of) headers would now point directly go into(/out of) the file node.