In-line topic search-and-linking, e.g. Roam-like bracket links

I think it’s time Discourse had a faster way to create links to other topics on a given forum. Obviously there is the existing link button and shortcut in the composer, and if you’re really brilliant and happen to know the exact URL of a topic you can even do it without using the link dialog. But there are other apps showing that there can be a better, faster, easier way: invoking a search-and-link dialog in-line.

There is already precedent for this in Discourse with the @ link/search behavior for profiles, as well as # link/search behavior for hashtags. So I’m simply suggesting that search-and-link for topics be added. This would take a very minimal approach, quite like the @ user search, with a quick pop-up in-line topic search based on text you type in the composer, and would not have any fields for Title or any other controls. It would work exactly like @ search except for links. You would use the keyboard to confirm the link, and the first option would be auto-highlighted.

One recently popularized syntax for this is “bracket links”, i.e. [[link-to-topic]]. You type [[ and a search of topic titles is invoked, just like the user or hashtag searches. Another common approach is a / slash menu, though this is usually used for multiple functions. However it is invoked, it would make it super fast and easy to create links between topics, which I personally view as a good thing as it encourages people to reference other existing and related content.

The main issue I see with this particular syntax is it’s different than the currently supported wiki syntax, but also similar. However wiki link syntax is actually used in systems that also support double bracket [[ ]] syntax, but specifically for links that need custom text. So one option would be to use that same distinction, double brackets for a link to a topic that uses the topic title as the link text, or a traditional wiki link for a custom title. Another would be to change link syntax overall, which I doubt is appealing. A 3rd option would be to pick some other in-line link syntax, i.e. a different set of characters that invoke the link search.

I don’t really care exactly how it’s implemented, I just want to be able to search-and-link in-line! I think it would be a great addition to Discourse’s already excellent composer and general convenience features. :slight_smile:

That said, I realize the existing Composer functions are quite good and this is only a convenience feature, arguably for a certain subset of users. It’s definitely a low priority even if there is agreement it would be useful.


Something similar exists when you select and move postings to a new/existing topic. Frankly speaking, it’s a PITA in its current form:

  • search takes long time
  • even if you know the topic title and type it in exactly as it is written (correct capitalization etc), the search does not find the topic you want
  • the search finds it, you select it, and then the search goes on before you even have the chance to confirm your selection. Your selection is gone, the search doesn’t even list your selected topic any more

My experience is just the opposite of that, see above.
I’m faster in finding the right topic whem I’m using the standard search function.

1 Like

Hi Oshyan, :slightly_smiling_face:

I really like the idea but…

Topic title is not unique so now when you search a topic you have other additional informations such as tags, categories to help recognize it more but inline might be too crowded and sometimes too many topic match your search to filter it inline.

Other thing:
When you use this panel to insert link you have to confirm your choice with a button click which is super useful I think.

In inline if you missed the correct topic you have to delete too much and maybe there will be more broken format links than now.

Maybe there is a good way to make it simple and fast but now I think the panel solution is faster and more user friendly.

1 Like

This all sounds like a result of failures of the UI/UX or search functions, not a problem with the idea of in-line linking itself. If you haven’t already, I’d suggest you open a topic to discuss improvements/fixes to the existing “move posts/merge” behavior, given the experiences you describe. But assuming those kinds of problems didn’t occur in the context of my proposed linking approach, would you then find it useful?

Why are you assuming that the in-line search would work any differently from the toolbar-based search? As far as the search-and-display behavior, it should work exactly the same and so would have the same level of ease and utility in terms of finding and selecting the right topic. My preference would be that it differentiate from the existing linking dialog and focus on speed and ease of use, working very similarly to the existing @ search that pops up a little contextual results list. The results list could look exactly like the one on the link dialog, but I don’t want a topic title field, an OK/cancel button, etc. There is already a shortcut that brings that up.

I really don’t know why there would be more broken links. You still need to hit Enter to confirm the topic you selected from the search.

Well, it’s definitely not “faster”. It may be more user friendly, sure, but my suggestion is not to replace the existing toolbar linking, just to add a faster way to link for more experienced users.

I suppose Ctrl-K (shortcut) is a fine alternative and already exists, of course. I just like the ability to use in-line syntax to trigger useful things, and it’s something Discourse already embraces with @ and # . Both of those could also just be accessible with keyboard shortcuts or manual typing without search, but of course there is added value in how they work now. I’m proposing that linking may gain similar value with this approach.

1 Like

Ah ok I understand thanks for the clarification!
This would be an advanced feature and keep the original search panel.
Seems to a good idea for me. :slightly_smiling_face:

1 Like

Just for clear context, what we have today is:

search for thing

For example: In-line topic search-and-linking, e.g. Roam-like bracket links

The trouble is that is is extremely hard to teach about it, but offers (arguably) a larger feature set than the [[ proposal.


Oh, that’s very interesting and good to know! However I do think there is a valuable difference between action-from-in-line-syntax and action-from-keyboard-command. Discoverability is one, speed is another.

It’s true that once you learn it, it’s reasonably quick to use that sequence, but having just tried it a bunch of times to test, it definitely feels slower and less smooth than my experience in the (growing number of) apps that support [[ ]] bracket linking. Perhaps this is partly because it involves a shift of attention/gaze, in addition to the novel and slightly awkward keyboard shortcut. The latter may be partially overcome in time (though my basic hand geometry sees some limits to that potential), but the attention shift is always going to have a cost during composing a message.

It’s actually interesting to me that you had desire enough for fast linking to create this somewhat unusual keyboard shortcut sequence (no doubt because many others were used). That suggests a bit to me that you might see some value in the in-line linking idea in general… But I do get the impression there isn’t much support for my suggestion for now. Even so, I’m curious to know at least whether there are any clear blockers to it, e.g. “We use brackets for something else”, “we can’t add another in-line handler or it will slow down all database queries by 30%” or whatever. :grinning_face_with_smiling_eyes:

Anyway, I hope this has at least piqued someone’s interest. I’d still love to have this available, and I imagine once other users had a chance to try it, they might also love it (any Roam users here at all? Obsidian? Logseq?). But at the least I hope I’ve piqued some interest in the idea of in-line search-and-link, and maybe something will crystallize around that in the future. :pray:

I see a [[ magic search as workable in a theme component today.

Only caveat is that the completion would strip [[ and replace with a link, not sure how else this could work. This makes ]] kind of pointless though

Keep in mind keeping auto complete open beyond a space boundary may be somewhat confusing


That’s good to know! As a non-programmer I don’t really know just how much is possible in theme components (a lot it seems, which is one of the many things I love about Discourse). So that’s pretty cool.

It’s true that in other software the [[ is retained and maintains some value even after the link is added. Or rather I should say, the [[ search doesn’t auto-fill a traditional link, but a specialized internal reference. Because multiple applications support that reference format, it’s portable in a variant of Markdown, so that’s pretty handy.

But anyway, in the case of Discourse [[ is just a familiar in-line shortcut, that happens to fortunately be unlikely to be triggered accidentally. I’d be happy with any other such text-based way to invoke in-line search that met similar criteria, but despite the differences in how it would work in Discourse vs. e.g. Roam, I do see some value in at least having the syntax be the same. Like I said, it’s something of a growing de facto standard. :thinking:

The other thing that occurs to me is that Discourse already has its own equivalent of internal links that get rendered in special ways: it’s how quoting works! So “post:10, topic:200454” will of course link to your reply to me here. Since this link function is intended to be specifically to internal topics, it could just use that and automatically display it as a link to the topic at render time. I can’t decide whether this is more in keeping with how Discourse does things, or less… :grinning_face_with_smiling_eyes:

On the one hand there is already this way of linking, this would just be a different way of invoking the link search-and-selection, and it is very similar to existing @ and # searches as I’ve mentioned. On the other hand it departs from existing linking behavior invoked by Ctrl+K, the toolbar, and other shortcuts. I think, though, that the “post:10” type of link is more similar to the [[ link concept concept as used in other apps, so I’d lean slightly that way… if I had any weight in the matter. :wink: I know of course that this is more theme component territory anyway, so perhaps I do! Maybe you can just weigh-in on whether “post:10” style linking could be done from a pop-up search in a theme component?

I just tried out Roam for context.

@codinghorror has mentioned a few times in the past how he is very concerned about how ineffective an inline search can be when you use the composer, though I guess that in the context of documentation and specific categories where stuff is scoped tighter is may be useful.

We had discussions in the past about introducing #784 type syntax which rings very similar to this discussion.

The way roam works:

  1. You type [[
  2. It magics in ]] and places cursor inside.
  3. As you type inside the [[ ]] it performs an auto completing search. Eg:

  1. When you finally decide on the link it uses full title eg: [[August 13th, 2021]]

  2. It handles renames of original document automatically updating markup in linking documents.

Anything similar to this behavior would require a pretty extensive plugin to Discourse, hooking into spots where topics are renamed, markdown engine and more. I would put this in the multiple weeks of complex work bucket.

Currently we have:


For an interesting implementation to note, I’d recommend checking out They use this syntax in Markdown files and it seems it’s similar to the spec @sam described.

1 Like

OK, so here’s where me using Roam as an example starts to break down if taken too literally. :grinning_face_with_smiling_eyes: I actually stopped using Roam quite some time ago, partly because its in-line search is completely awful. Obsidian is a better example and it’s what I use full-time now, but it requires a download to try and Roam (or Logseq) do not.

Before I go any further, thank you @sam for engaging so much with this idea, which I realize may be a bit out of left field. And especially for giving me a ballpark of the work you think it might take, at least in the way that you’ve outlined it working.

That said, I want to stress that my suggestion is inspired by Roam and similar apps that use this syntax, but I am not interested in trying to fully replicate everything about how it works.

  • It doesn’t need to auto-complete the bracket because the bracket will not be kept in the resulting markdown (in Roam it does keep it, same in Obsidian)
  • Discourse search, as exemplified by Ctrl-K link search, or Ctrl-Alt-F, is better than Roam and, if instantiated in-line, would probably allow me to find a topic of interest in a reasonably short amount of time (i.e. if you think search is useful at all, then it would meet the need described here as-is)
  • Link would use full title, just as if you copied/pasted a link to a Discourse topic in to that same forum in a message
  • Renaming would be handled however Discourse already handles that for internal links

So, to sum up, Roam is just an example to demonstrate the concept and part of the user experience. What I am really suggesting is:

  • Some set of uncommon but quickly typed characters that can trigger an in-line topic search
  • In-line topic search with Enter to select first result automatically
  • Regular Discourse link handling in all other respects
  • Implementation in whatever way would be most in keeping with the Discourse approach to things

The rest of what I’ve said is just musings on what might make the most sense or possible approaches to the problem.

So with all that in mind, does that change the estimate of work required? If not, what exactly about the feature request is making it so much more complicated than e.g. Ctrl-Alt-F + A? I ask because that might help me understand if I can narrow the scope of the request to make costs reasonable, or if it’s just not worth the time needed.

Thanks again!


For me, the less compatible Discourse is with regular markdown, the harder some other things would become, like moving content between Discourse and other things that use markdown. (My sites and documentation generally use markdown or MDX.)

If some kind of feature like this gets added, an alternate idea for implementation would be to use a system similar to Confluence or Notion where the / (slash) character opens up a menu.

Here’s Confluence:

Here’s Notion:

Notion slash commands

If a similar feature were in Discourse, a slash could open up a menu which would include “Link” as an option. If “Link” is selected, then the user could do a search for other posts and a normal markdown link would be inserted in the editor.

I’m not requesting the feature but am just mentioning an alternate idea for implementation that wouldn’t make the raw content diverge further from regular markdown. :slight_smile:


If you keep stuff within the existing structures then a theme component can work just fine and the amount of work is not enormous. The [[ is actually handy implementation wise cause it gives you a nice anchor of where to stop with auto complete.

A full workflow example could be:

  1. User types: [[
  2. Composer fills in ]], cursor is in between the brackets.
  3. User types search term eg: [[in-line topic]]
  4. As user is typing search is performed and results rendered in a autocomplete like @mentions
  5. Hit up/down/enter to select.
  6. Once selected [[in-line topic]] is replaced with
  7. If user just moves cursor beyond ]] autocomplete closes and a [[in-line topic]] would just stay in the markdown

Overall building something like this is totally feasible in a theme component , does not amend any server side stuff and would be pretty straight forward to build. I would say an expert could swing something in a day or two, an intermediate would probably take a week or so.


Yeah, slash menus are definitely an interesting and cool approach that I like and use in a lot of apps. I think it didn’t occur to me as the way to implement what I wanted in this case because that approach implies a whole set of functionality to be invoked. In other words I think it would be weird/unexpected, for those used to slash menus, for one to only invoke a link search. And while having a lot of other functions on a / menu would certainly be something I’m in favor of, it sounds like a notably bigger feature request to me.

Fantastic, thank you for thinking this through and giving me some idea of the complexity and dev time! That is extremely helpful. I will have to think about whether I can put some of my own money toward it, as I have some other perhaps more important requests I probably need to fund for development. And now that I know more about the keyboard shortcuts this one is more a convenience than necessity anyway.

1 Like