Everything is a block in Roam Research. This makes the block reference feature very powerful.
The main purpose of block references is to avoid duplicate content in your database. The idea is that you only need to type something once and you can then use it in as many contexts as you like. With the August 10, 2020 update of Roam, users have gained a few more possibilities to work with block references.
In this article, we describe the behavior of each option in the block reference context menu.
Add a block reference
There are several ways to reference a block in Roam, but the easiest way is to type double brackets and one or several words that appear in the block you want to reference. Say we wanted to reference a block with the content “Parent block”. We could start by writing ((parent)) and Roam returns suggestions:
Select the block and click with your mouse or hit Enter on your keyboard to reference it. The block’s address is now added, making it a reference:
Hit Enter or click outside the block to see its contents. When you hover over the block, you’ll see an arrow, indicating it’s a block reference:
Clicking the block opens the block reference context menu:
We will now have a look at each option and its behavior.
Jump to block
The first option of the context menu is Jump to block:
Clicking it, you’re taken to the page that contains the block, and zoom in so you only see the block and its children:
Open in Sidebar
Selecting the option Open in Sidebar opens the block reference and its children in the sidebar. This behavior is similar to the Jump to block option, with the difference that it’s opened in the sidebar. Option:
Result:
Replace with
With the block reference context menu we gained a few possibilities to manipulate block references. Before, you could only show the contents, but now we have more possibilities to mix and mash.
Embed
If a block reference is like a window to a block that prevents us from touching it, the block embed function is a portal to a block that does enable us to edit it directly. By selecting the Replace with embed option, the contents of the embedded block and its children become directly editable. Option:
Result:
Text
The Replace with text option opens up many possibilities. Sometimes, you do want duplicate content in your database, or you want to use most of the contents of a block but want to change just a few words. This is where replacing a block reference for its actual contents is useful. Option:
Result:
Alias
When you select the Replace with alias option, the contents of the block reference will disappear and a link to the block will appear. Option:
Result:
When editing the alias, you can see that Roam uses the Markdown for an external link/alias and uses the block’s address as input:
Text and alias
The Replace with text and alias option combines the previous two options. What it does is duplicate the contents from the referenced block, and add a link to the original block. This enables us to change a block’s contents, while making it easy to quickly jump to the original version. Option:
Result:
This is what the contents look like when editing the block. As you can see, the text was added with the alias link that we saw previously:
Apply Children
So far, we’ve been working only with the block reference itself. But, as Roam is an outliner that allows you to nest blocks under other blocks, more options open up. The Apply Children option is a useful way to create templates in Roam. We’ll now have a look at the two options in this submenu.
As text
The Apply Children as text option pastes the children of the referenced block underneath as text. The top-level block reference stays, but nested underneath it are text blocks with the contents of the referenced block’s children. Option:
Result:
If the children of your referenced block have children, they will also appear with this option:
As references
The Apply Children as references option is almost identical to the last. The difference is that the children will appear as references. This is useful if you use this feature for templates and want to keep track how often you used a template (for example journaling prompts). Option:
Result:
Again, if the children of your referenced block have children, they will also appear with this option:
Copy this Reference
This option copies the address to the block you’ve referenced.
Delete Reference
This option deletes the reference:
This option does not delete the bullet. So, if you have other text in the block apart from the reference, only the reference will be deleted but not the surrounding text:
Result:
Join the conversation.