Block reference

It would be great if Obsidian could handle block reference similar to Roam Research. That would allow users to reference smaller-than-header chunks (block) of another file. If the referred block changes, it would change in all files that make a reference to it.

This feature is like the stage 3 of transclusion (full file transclusion as stage 1; header transculsion as stage 2).

Possible relation to other feature requests:


This is not simple, because Obsidian is document-based and doesn’t really have a concept of ‘blocks’ like roam does
There’s been some talk about adding hidden IDs to the end of each line, allowing you to uniquely identify them for embedding, which may be the only way to keep track of lines without going beyond markdown


I absolutely appreciate this is not a simple ask for a markdown-based solution. The feature is still interesting, in spite of the implementation complexity, though :wink:

The ID sounds like a feasible solution. Another solution would be keep track of each line/paragraph/bullet in a markdown file externally somehow. That would be hard to manage if the user edits the .md file externally to Obsidian, but might be aan avenue worth exploring.


This is one of the coolest features of Roam. It would be a shame if Obsidian never had it


This would also cripple portability; the .mds are easy to take with you to another application, the database not so much. The advantage of the id-based solution is that even if you migrate elsewhere (I’m not planning on abandoning obsidian anytime soon but want the option :slight_smile: ), the IDs are still there so you can still understand those references even if the program opening them doesn’t.


This comes up a lot, and I’ve come to terms that Obsidian may never have in-note referencing/transclusion like Roam. Perhaps someone in the far future will write a very complex plugin that embeds and tracks hidden identifiers, but as has been mentioned, there are a lot of caveats to this.

Another way to look at this is that referencing/transclusion is a relative unit. You can use Obsidian notes as Roam blocks and embed them into larger notes. I think there is an entire feature set required to make this doable, but that seems more achievable than trying to replicate outliner features inside of plaintext.


I understand your point, Sam. It seems we agree that this is a desirable feature. The problem is how to implement it, which is a valid concern, for sure.

As a user, I don’t really care about how this would come to life. As an engineer, though, I totally appreciate the challenge… and I still believe it is a valuable feature for Obsidian :slight_smile:


@Sellaro Totally agree, just brainstorming about the best way to get there.


I am using header transclusion heavily. But there are a lot of challenges with that approach. The first and obiovous one is that if you change the header wording, you will break your transclusions all over (![[file#header]] is weak id, in other words).

A second problem is that you basically increase the granularity. Instead of having one file per note, you will have one file per note block.


Yes, I’m not totally comfortable with header transclusion for those reasons and the fact that it’s not portable (although maybe Obsidian will lead the way in adoption). I like to use header linking for some of my summary/index notes, but it doesn’t feel reliable for fully linking ideas.


Maybe something like that

| Block content
| with muliple lines

block_id would be some random string bzsDAcg6B9 or ZK style 20200528210434.

To make it easier there should be shortcut/button to quickly add this block template and move there user cursor, or even modify already existing, selected text:

| <user cursor or selected text goes here>

Type (( to autocomplete, similar to Roam. Currently content can be rendered only in preview mode, later with new editor it could be visible in editor too, with collapsible header with clickable path to original location and buttons to edit/remove that rendered block. Should be obvious for app where the original is - it have to search for ((block_id with | directly under it.


I have been waffling on this. As of now, I’m actually against block-level linking/transclusion.

Can I ask: what is the exact use case for this, for anyone interested in the feature? What do you need or want to do with block-level links? I’d love to see a collection of purposes. Otherwise, I don’t think “because Roam does it” is a great rationale for implementing the feature.

There was a great chat about this on the Discord a few days ago. Someone pointed out that legal and religious documents often have singular lines that are scrutinized and reflected upon. This seems like a good example of what block linking makes easier, though I’m not convinced that creating a new note with that line as a header isn’t an equivalent or better solution. So, I’m keen to hear more!



Reading over these thoughtful posts, I’m warming up to a targeted block reference - snippets of text that can be wrapped in some hidden reference. That’s a lot different than Roam’s implementation of “everything is a block” in an outliner format. I’m thinking that in the Obsidian implementation, the user would have to define the start and end points of the reference. Instead of the term “block”, how about “clip”, “snip” or “snippet”?


Provided that we are able to keep consistency across the whole vault, that would be great!

1 Like

Yes, that’s the challenge. What happens when these references move or change? That problem hasn’t been solved for header references yet.

1 Like

Hi, @ryanjamurphy.

Thanks for your remarks here. For sure the feature is not only “because Roam has it”. The concept of block reference and transclusion is much older than Roam and is quite useful, although it takes a bit to get used to the idea. Once it clicks, you’ll be asking why the hell you’ve lived so long without knowing this ::wink:

The Bible case you mentioned is just a tiny example of what can be achieved. Think also about evolving documents, where you can make reference to tiny bits of information (block) while working on both: the block and the document itself (any writing project can benefit from that: articles, thesis, books, …)


I’ve been requesting for this feature since I first started using obsidian beta, and although I am code-illiterate, can tell how difficult it would be to achieve this functionality.

for now, as some people have already mentioned, I’ve just been trying to make each file as granular as possible, and when appropriate to do so, to sort of work as a “block”, nesting links into larger notes

would be interesting to see what people come up with in the future as a work around! perhaps some neat plugins :slight_smile:


Not to disagree, but to challenge: I think there’s an important difference between a feature being used and it being useful.

The entire Internet operates—very successfully!—without block referencing. So the question is, what can we do better (i.e., more effectively, efficiently, easily, etc.) with block referencing than with currently-available feature sets? Put it a different way, what are the affordances of block referencing, and are those affordances worth the effort of using them?

To repeat and to be clear, I’m not saying that block referencing doesn’t improve upon anything. I just want to hear some clear and concrete examples of workflows in which block referencing would leapfrog what we can do already.


Block referencing allows me to include the information in a paragraph in a separate document without copy/paste. Then if I edit the block it is edited everywhere. It is hugely powerful. I’m loving Obsidian but have not yet cut the cord to Roam specifically on this one issue. Where I see Obsidian “not yet there” is on workflows that allow me to compose in one note while rapidly scanning for and incorporating content in other notes. I may not have figured it out yet but currently I’m finding it quite kludgy to edit in one window and then review other windows for content to include.

An example workflow in Roam that has been linked in these forums before:
Nate Eliason using Roam to quickly outline article

Personally including blocks from other pages as a linked quote is a huge part of creating summary pages etc on a given topic.


In the most simple sense, it’s an extreme/advanced quoting. We’ve been quoting forever, block level transclusion is just leveraging tech to allow quotes to be “live” & their transformation/use to be traceable.

Hyperlink & hypertext was always supposed to have bi-directional links, and the ability to tracing sources/changes to the origin/steps, since the beginning of the internet. We’ve had a nerfed version of what the next could have been due to it.