# Link to Headings: How to show headings in org-insert-link?
**URL:** https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138
**Category:** Requests
**Created:** [January 4, 2021, 4:42pm UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138 "2021-01-04T16:42:06Z")
**Posts on this page:** 14
**Page:** 1
### Author:  [@nateneff](https://org-roam.discourse.group/u/nateneff)
#### Post date: [January 4, 2021, 4:42pm UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/1 "2021-01-04T16:42:06Z")
I just watched this video about how to link to org-mode headings:
[ ](https://www.youtube.com/watch?v=oyEMlIxIHXs)
I created a heading in [Foo.org](http://Foo.org) 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:
> **[\*Minibuf-1\*](https://www.evernote.com/shard/s226/client/snv?isnewsnv=true¬eGuid=c104a87a-9ac8-416f-90b7-7f16d0764076¬eKey=edb4e20e80489a7c&sn=https%3A%2F%2Fwww.evernote.com%2Fshard%2Fs226%2Fsh%2Fc104a87a-9ac8-416f-90b7-7f16d0764076%2Fedb4e20e80489a7c&title=*Minibuf-1*)**
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.
Thanks,
–Nate
---
### Author:  [@nobiot](https://org-roam.discourse.group/u/nobiot)
#### Post date: [January 4, 2021, 6:38pm UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/2 "2021-01-04T18:38:18Z")
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](https://org-roam.discourse.group/t/how-to-to-get-title-of-the-target-note-working-with-inline-autocomplete-in-org-roam/782), for what’s worth. It would need updating, but I believe you could get a gist.
---
### Author:  [@nateneff](https://org-roam.discourse.group/u/nateneff)
#### Post date: [January 5, 2021, 1:43am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/3 "2021-01-05T01:43:35Z")
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?
---
### Author:  [@danderzei](https://org-roam.discourse.group/u/danderzei)
#### Post date: [January 5, 2021, 2:31am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/4 "2021-01-05T02:31:57Z")
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.
---
### Author:  [@nateneff](https://org-roam.discourse.group/u/nateneff)
#### Post date: [January 5, 2021, 3:58am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/5 "2021-01-05T03:58:18Z")
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?
---
### Author:  [@mshevchuk](https://org-roam.discourse.group/u/mshevchuk)
#### Post date: [January 5, 2021, 8:41am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/6 "2021-01-05T08:41:59Z")
> [@nateneff](#):
>
> Org Roam already duplicates a completion engine by providing links with org-roam-insert.
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.
---
### Author:  [@mshevchuk](https://org-roam.discourse.group/u/mshevchuk)
#### Post date: [January 5, 2021, 8:53am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/7 "2021-01-05T08:53:28Z")
> [@nateneff](#):
>
> 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?
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.
---
### Author:  [@nobiot](https://org-roam.discourse.group/u/nobiot)
#### Post date: [January 5, 2021, 2:15pm UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/8 "2021-01-05T14:15:23Z")
> [@nateneff](#):
>
> so why not individual headings?
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.
> [@nateneff](#):
>
> I wonder why a separate plugin would be needed
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??).
---
### Author:  [@nateneff](https://org-roam.discourse.group/u/nateneff)
#### Post date: [January 5, 2021, 2:54pm UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/9 "2021-01-05T14:54:10Z")
> [@mshevchuk](#):
>
> No it doesn’t. It only supplies candidates to an existing completion engine. But that’s not the point you are indeed missing.
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.
Thanks,
–Nate
---
### Author:  [@nateneff](https://org-roam.discourse.group/u/nateneff)
#### Post date: [January 25, 2021, 9:50pm UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/10 "2021-01-25T21:50:03Z")
Yes! Looks like good news!
[Org-roam major redesign](https://org-roam.discourse.group/t/org-roam-major-redesign/1198) Bravo @jethro
---
### Author:  [@Jason](https://org-roam.discourse.group/u/Jason)
#### Post date: [March 4, 2021, 5:37am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/11 "2021-03-04T05:37:35Z")
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)`?
---
### Author:  [@nobiot](https://org-roam.discourse.group/u/nobiot)
#### Post date: [March 4, 2021, 8:47am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/12 "2021-03-04T08:47:11Z")
Maybe. Not sure, too long ago. What’s the result on your end?
---
### Author:  [@Jason](https://org-roam.discourse.group/u/Jason)
#### Post date: [March 4, 2021, 11:25am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/13 "2021-03-04T11:25:49Z")
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.
---
### Author:  [@nobiot](https://org-roam.discourse.group/u/nobiot)
#### Post date: [March 4, 2021, 11:53am UTC](https://org-roam.discourse.group/t/link-to-headings-how-to-show-headings-in-org-insert-link/1138/14 "2021-03-04T11:53:54Z")
I don’t. I realized company mode is not for me for prose writing, so I don’t use it in Org Mode altogether.