Link to Headings: How to show headings in org-insert-link?

I just watched this video about how to link to org-mode headings:

I created a heading in called “Bar” and created an ID to that heading using org-id-store-link.

Now, I would like to see that heading “Bar” in the dropdown when I call “org-roam-insert” - however, I only see my org-roam files.

I tried calling the org-roam update, but “Bar” does not appear in the dropdown. Am I simply missing something? This IMHO would be another killer feature of org-roam, because (to my knowledge) org-mode does not do a very good job of helping me insert links.

For example, after creating a link to “Bar”, the org-insert-link function gives me a horrible dialog showing only the silly UUID instead of the heading:

Org-insert-link also only “remembers” links which have been created in this session.

Again, I thought that org-roam would be the savior here and show me a list of org-roam files and headings which have an ID property, but it appears that I’m doing something wrong with org-roam, or that the “easy to insert a link to a heading” functionality that I’m looking for doesn’t exist.


I don’t think org-roam-insert currently shows the headlines listed together with the titles.

How about using company-at-point?


A bit old config discussion here, for what’s worth. It would need updating, but I believe you could get a gist.

Thanks @nobiot, but I wonder why a separate plugin would be needed - unless I’m missing a major point of org-roam. It seems like org-roam is smart enough to know about my files, so why not individual headings?

One of the powers of Emacs is that all packages can build on each other. It would not be good if Org Roam duplicates a completion engine. Org Roam already depends on many other packages that are installed invisibly. Using company is just another dependency.

Org Roam already duplicates a completion engine by providing links with org-roam-insert. The software simply doesn’t care about links to headings which doesn’t make any sense to me. If a heading or a file can be a link, then why not show the headings?

No it doesn’t. It only supplies candidates to an existing completion engine. But that’s not the point you are indeed missing.

Org Roam was designed with files as analogs of Zetteln (German for sheets of paper, cards) with Org Roam itself being a Zettelkasten - a card box - a slipbox. In its database it stores relations between files and as far as I know doesn’t know about headings at all. Headings are not the first-class citizens in Org-roam. They are more akin to a bulleted list on a card. I’d argue it would make little sense to have links to individual items of a list - and the original paper-based system did have a linking system - because cards are small enough, usually half a size of a standard letter/A4 sheet, to locate what you are looking for instantly. So users of Org Roam are also encouraged to keep their zetteln-files small enough - maybe you don’t need headings at all?

This is where a lot of misunderstanding comes from, especially for long-term Org-mode users, who tend to have large files accumulating all their notes there. In principle, it would be equally easy for Org-roam to treat headings as atomic notes, in which case a file holding the headings would become a whole zettelkasten. The creator of Org Roam deliberately decided against such a system and I personally fully agree with and support this choice. This is not the first discussion of its kind, you can find additional arguments for a file-based system elsewhere.

1 Like

Here I can agree with you. That headings have been leveraged to something more than an item in a bulleted list without a means to conveniently insert links to them is an inconsistency. However, if you watch the video to the end, starting at ~4:30 it is told that “UX for inserting links to headlines” is under development.

Of course it is up to you whether you embrace the Zettelkasten method embedded in Org-roam, and the degree to which you follow it.

Technically, I would estimate it to be many additional person-hours to implement headlines to appear in the list. As with the title of a file, you might need to cater to the fact that headings may change often (maybe more often than the file’s title). I do not believe headings are stored in the cache DB at the moment, so the foundational functions would need to be built. You might be up for a challenge of implementing this yourself – no sarcasm intended. If you feel strongly about “lack of” features, others might feel the same way, and your contribution would be a welcome addition. I personally do not rely on headlines in my notes, so I didn’t even notice what you see as a missing feature.

Yes, my demo shows use of Company, a third-party plug-in. I think there are benefits of trying to avoid plug-ins. Org-roam does not implement a completion framework of its own (as @mshevchuk mentions), but uses a Emacs built-in “APIs” so to speak (@danderzei is alluding to this by pointing to the benefit of letting you compose your own workflow); in this case, completion-at-point – it’s built-in in Emacs minibuffer. You can use it directly without Company, like so:


Org-roam is built to let you use completion-at-point with it; that’s why a third-party plug-in like Company can be used without modification (I think I got this right??).

My apologies - this is what I meant. Also, I recall watching the video and seeing the note about the “UX for inserting links to headlines” after you mentioned it here - I was simply “swimming” by the time I heard that statement, so it didn’t register w/me.

As you probably know, I haven’t “grokked” org-roam just yet. I think I’ll
“wait” for a UX in upcoming versions of org-roam. Plugins are fine, except
in this case it seems like there will be this functionality in future versions.

It seems there’s a lot that I don’t grok about org-roam.


1 Like

Yes! Looks like good news!

Org-roam major redesign Bravo @jethro

Hi, I noticed that after the completion of the file name and typing a *, it doesn’t show me the headings list. Did you achieve that by setting (setq company-minimum-prefix-length 0)?

Maybe. Not sure, too long ago. What’s the result on your end?

I could get the headings completion list to show by setting company-minimum-prefix-length to 0, but I feel 0 is a bit too intrusive, as it constantly pops up a candidate list as I type. So I wonder whether you have a better solution or not.

I don’t. I realized company mode is not for me for prose writing, so I don’t use it in Org Mode altogether.