Namespaces: how do they work?

One feature a lot of Roam users are after is a way to differentiate between different [[pages]] with the same name. e.g. [[Harry Potter]] the series vs [[Harry Potter]] the character.

A feature mentioned in this tweet, called namespaces, seems like it might be useful here. The premise is that you place tags in the front of the page title, followed by /.

e.g. [[book/Harry Potter]] vs [[character/Harry Potter]]

You can then hide those tags by pressing ctrl+c+l - at least, according to the tweet. For me (working on Mac/iPad), nothing seems to happen with that particular hotkey.

Does anyone know of any detail documentation on the subject? Potentially this could prove very powerful, especially if upgraded with more functions later down the track.


The shortcut is Ctrl-C followed by Ctrl-L.
Repeatedly hitting that combination rotates between [[b/Harry Potter]] [[Harry Potter]] and [[book/Harry Potter]]. It works on Mac and iPad.

The only other feature of namespaces right now is on export. Namespaced notes will be in their own namespaced folder.

It is documented in the help database, just ‘expand all’ on the node in linked references.


Very strange. Even with all CSS and Javascript turned off, the hotkey doesn’t seem to work on my end. Anything I could be missing?

Namespaced pages enable disambiguation - as the example in the Help database demonstrates, unrelated pages that happen to have similar common names can be viewed with exactly the same visible name - in the example, its “Tree”.

Less publicized but just as useful, namespaced pages facilitate finding connections as well. With longer and more useful page names we can create mini-structures for areas of a databases, broadening the potential link search space for pages without cluttering viewing those pages.

For example, someone was using Roam for knowledge management where a subtopic of another topic emerged, in his case “Economy -> Capitalism”. Now by creating three pages as below (and toggling namespace visibility down to the minimum), we will have:

  1. [[economy]]
  2. [[capitalism]]
  3. [[economy/capitalism]]

With toggling, [[economy/capitalism]] will appear as [[capitalism]] just in a different color, with the economy/ prefix hidden. This means that the unlinked references of [[economy]] WILL include mentions of [[economy/capitalism]], with [[capitalism]] in a different color. There are a lot of ways to use this, depending on what one is trying to achieve. Finally, different forms of names (abbreviations, nicknames, initials, numbered foot/endnote references to a page) can be made more explicitly connectable to the visible name by namespacing. There can be more than one degree of namespacing also. For example: [[New York City/New York/NYC]]. If you see an unlinked reference you want to connect - be careful doing it automatically. Auto-linking to a page name that is also a component of a namespace will insert page links with full [[]] into the page name of the full namespace - messy in some cases. While wonderful for finding connections, consider linking specific pages explicitly.


Topic hierarchies are a big part of the appeal of namespaces for me - as you say, it makes sense that a block mentioning capitalism is also referencing economics, and having to type #economics manually takes up extra time/space. Very useful (and I’m sure Roam will add more uses for namespaces later on).

I’m not sure why the hotkey to hide namespaces isn’t working on my end, but I’ll probably carry on using namespaces regardless and wait for a fix.

1 Like

The shortcuts weren’t working on my mac either, until I discovered I had co-opted them in another program - Keyboard Maestro. As soon as I deactivated them, CTRL-C, CTRL-L started working correctly, in Roam.

1 Like

Wow, namespaces. I never knew they existed. I’ll have to play with that.
FWIW, my method of disambiguation thus far has been to use a leading emoji. For Tree it might be:
[[:fallen_leaf: Tree]] for the plant context
[[:triangular_ruler: Tree]] for the math context
[[:green_book: Tree]] for a book context
Of course, you can use any icon that you identify with for each context. I spend quite a bit of time carefully choosing emojis that are not too garish as to be distracting, but once chosen, I keep them in a favorites and program Keyboard Maestro so they are easy to call up.


Just made a thorough search but can’t seem to find where either of those shortcuts are being used. Same issue across Chrome and Safari, on both Mac and iPad.

One solution might be to have a settings menu in Roam where these kinds of tweaks can be made without using hotkeys.

1 Like

I’m tempted to merge prefixes into namespaces. So Book: Title would be Book/Title. I presume that the prefix Book is still useful for autocomplete, and the appearance in blocks would be clearer, but I wonder what the downside might be in this system. Does anyone use it like this?


Looks like the hotkey is working after all. The problem was that all the links I had namespaces for were film/artwork titles with __ italics __ markers in the link title. Apparently that breaks namespaces at the moment.

This is how I’m using namespaces. Many people are using some short prefix like “B: Title” for books, and “P: Project Name” for projects. I have chosen to go down the namespacing route, so book summaries are “book/Title” and “project/My Project Name”. It’s slightly more effort in typing for the autocomplete, but I think it’s less ambiguous personally.

The only real downside is that you can’t use page references or other formatting in the page title, which can be useful on occasion.

I am banking on further useful functions coming to namespacing in the future.


Same problems here, do not have them listed as any hotkey anywhere else. I’m on Linux and most things even browser-based do not work the way they are intended to, so there is a bunch of the shortcuts I cannot use at all.

I was very excited when I read this title but only got more confused the farther down the comments I got and that guys GIF on Twitter just made my head stop working entirely. xD

I look forward to being able to understand this better!

1 Like

Ryan Guill’s formatting converter has been updated to remove namespaces from Roam text! You can find the web app here.

1 Like

I’d like to understand better the benefits of using namespaces. I can see how it might be useful to distinguish the fruit “apple” from the company “Apple” without requiring capitalization, but beyond that, are there benefits to using namespaces for other tags? For instance, if I used the “people” namespace for all names would that allow me to see or manage those names in any useful ways? Or is it mostly useful just for disambiguation?

1 Like

Currently the main benefit (aside from distinguishing between concepts with the same name) is that you do get Unlinked References to the namespace categories. So if you use the namespace film/ for all of your film titles, that will create an Unlinked Reference to [[film]] every time you use that namespace, even if you have namespaces hidden.

Of course, in the future, I imagine Connor will upgrade their capabilities (along with enhancements to Attributes). Anything that helps to automatically categorise data is a big plus in Roam.


That sounds like a problem as much as a benefit. So the unlinked references on a page might be swamped with all those of the same category. Is that what you meant?


The unlinked references are for the namespace itself. So if you type [[film/Star Wars]], it will show up as an unlinked reference on the [[film]] page (the same as if you had typed “film” as normal text.

1 Like

How about @cortexfutura’s [[name {[[spacing]]}]] ?

Any idea how I can ‘Query’ the namespaces that I’ve created?