How to do block referencing in Obsidian

Edit: Since block referencing and embedding was implemented in 0.9.5, this workaround is no longer needed.

Can Obsidian do block linking?

Yes, but it behaves differently from other PKM apps. Create a block reference by wrapping the target block—or sentence, or phrase, even—in [[square brackets]]. Then, create a new note with this link. There! Now you can reference that “block” elsewhere.

You may add content to the new note, but you don’t need to. A best practice might be to include a link back to the “originating” note at the top of the new note, just to make it easier to navigate back to the original block.

In other words, block linking and embedding is easily possible as long as you accept that you’re “creating new notes” to facilitate the feature. This happens behind the scenes in other PKM apps, but it enables interoperability and data ownership in Obsidian.

An additional constraint: blocks referenced in this way must abide by the filenaming rules of your OS.

- - -

One of the most common qualms about Obsidian takes the form of a question: “Does Obsidian have block referencing?”

Licat has a diplomatic response:

You can link to/embed headers right now which works for most use cases

However, this doesn’t need to be true. Obsidian does have block linking.

Roam Research’s block linking is possible because Roam treats every line as a unique data object, attaching a unique ID to each one (along with some other metadata, I’m sure). Obsidian, instead, uses plain text files. Ergo the lines of text are not uniquely addressable without additional workarounds, some of which may violate the principles behind working with plain text.

Roma’s block linking is possible because it doesn’t “have” or “use” files. However, the files exist as data objects. Every block is its own file. In Roam, you just can’t see those files.

In Obsidian, you can.

So, if you want block level referencing, in Obsidian, you just need to wrap the blocks you’re targeting with [[ ]]. Then create the new note. If you want, you could then include a bit of text in the note referring to the originating note to aid navigation later.

Tada. You can now reference and embed that block anywhere. It doesn’t matter that the linked note contains no text. Its own Backlinks will lead you back to the original note. Edits to the link will rewrite the note title and other backlinks. Magic!

This is actually the same thing Roam does, under the hood. The only difference is that block linking here requires an extra step when creating the block reference (initiating the link) and when going back to find the original note (this requires two steps instead of one).

But you can have your cake and eat it too.


I think you’re onto something here, and I agree that “blocks” could be the note/file itself, but isn’t there a major limitation with note titles being filenames? The content I wrap in [[]] would have to be a valid, unique filename to be created as its own note.

I assume this is solvable, but doesn’t seem Obsidian is there yet. Personally, I think we need separation between note titles and filenames.

What do you think?


I see your point.

Descriptive filenames facilitate interoperability. It makes it easier to open and work on your ideas in Obsidian directories in, say, iA Writer.

If we abandoned filenames-as-links, the best approach would probably be to generate unique universal identifiers for filenames. Titles of notes could then come from H1s, as you suggest.* (An alternative approach would be to leave the filename as whatever it was to start with, but I think that’s the sad kind of compromise where you cut the baby in half.)

I suspect that the community will be divided about such a decision. Arguably it would violate one of the principles at the core of the app—ownership (and usefulness) of your files outside of Obsidian.

At the same time, it is sad that you can’t use apostrophes, colons, question marks, or other characters as block references according to the method I’ve proposed. (Although arguably such note titles align with recommendations from wizened pros.)

I think I’m willing to accept that constraint in order to preserve Obsidian’s core principles. Still, I’m interested in alternative ideas about file names and note titles!

* A better option, I would argue, would be to use Multimarkdown/YAML headers, like Title: Some note title at the top of the note. H1 actually does correspond with level 1 headings in XML, while Titles are typically their own XML entity.


Overall I think this is a workable idea, however my most atomic units are usually latex equations.


Perhaps we are firmly in plugin territory on this, which allows us to extend the core app principles :smile:

I don’t think we need to abandon filenames as links inside the source markdown for portability. What I proposed in my feature request is that Obsidian uses a different “display name”. I am hoping the future WYSIWYG editor and other components (search, graph, etc.) can create useful abstractions for note titles.

Great idea - I updated my feature request.


I had some thoughts about that subject. I don’t really understand programming, so forgive me if I point out s.t. what is already described. But maybe I can add an Idea :wink:

The idea of having a textsection/block referenced via the filename (hope I understood that right), seems viable but I think it has the disadvantage for things to get quite chaotic (they will always pop up when searching for notes, you have these “random files” which gain meaning just by they are linking to other notes)

I like the idea of obsidian working just with plain text and that adding a feature, which ads ID’s to every text line just doesn’t seem to work with this sort of file.

As far as I understand when creating a markdown header, there is an ID created which can be linked to. (And this is used already). So, it’s seems to me, that it is already possible to create an ID to a certain text part within a markdown file. But in the current state of Obsidian it can’t be used conveniently for the referencing purpose.

  • When changing a header in an original file, files that linked to this header doesn’t get updated in the way it works, when changing the filename of a note. But maybe it isn’t that hard to implement in the software, to update all files when a header is changed.

  • As for now, the whole “path” is displayed when referencing to a header. So, it would be necessary to have an option to just have the referencing header to be shown or it can’t be read properly.

  • When creating a header, the appropriate formatting is added to this. I think to be more broadly excepted, a form of header with no formatting would help.

I think of a kind of “special referencing header” (maybe invoked with its own command).

  • it creates an ID for referencing a text at the points where you need it (instead of creating ID’s for everything).
  • it hides the formatting so it looks an behaves like usual text
  • It would update when being changed
  • it would prevent the accumulation of “referencing notes”, and it would be still possible to create a note file of its own when needed
  • in another application it would show of as “plain text” to be read

This would seem really powerful to me, without having to give up the plain text tenet. Can s.t. like this work?

1 Like

Hi @ryanjamurphy,

Tada. You can now reference and embed that block anywhere. It doesn’t matter that the linked note contains no text. Its own Backlinks will lead you back to the original note. Edits to the link will rewrite the note title and other backlinks. Magic!

I’m experimenting with this now, but on my end it does not seem that editing the link changes the note title and other links - instead a new note with a different title is created. Am I doing something wrong?

On a more general note, this solution could work in a pinch, but the limitations are just too great and things quickly get really ugly in the File Explorer as well. I do think having blocks as separate notes is fine - it actually makes sense in a way - but agree with others above that there should be a way to display the note content as the link without it being the actual title/file name.

A good workflow for this could be a hotkey that takes a “block” (sentence/paragraph or whatever, really) and prompts you for a shorter note title/file name or creates one automatically (could be the zettelkasten time stamp), ideally this would be a setting since preferences may vary here. Then it would create a new note with the selected content and title and replace the original content with a link to the new note, that actually displays the original paragraph, if that makes sense.

It would also have to be searchable when creating links, so some extra title tag seems to me to be a reasonable solution. Just my three cents. :sweat_smile:


@FriSti I couldn’t say for sure, either way, but my instinct is that the kinds of generated IDs you’re describing wouldn’t be simpler than the text they’re standing in for. The only way to get a simpler ID for a given line in a given file would be to generate it, and then you’re either appending that generated ID to the plain text somehow or maintaining a separate index data file in your Obsidian vault somehow. The latter is likely the direction a successful block referencing plugin will take, once externally-developed plugins are possible.

@Hitchhiker90 Sorry, good point. I hadn’t thought of two-way editing in my “solution.” I wouldn’t expect the filename to change when you changed the [[reference link]]. It’s possible, though, that an embed would work? These are of the form ![[reference link]] (note the preceding exclamation point). I haven’t tested this myself.

1 Like

@ryanjamurphy Thanks for the clarification. It’s impossible to change the file name this way, even with embedding.

Embedding does work but the embedded bit really stands out, so it could be useful in some cases, I guess, but it does have a different feel to it.

Anyway, maybe it’s best to wait and hope for a plugin.

Ah, there are some CSS themes that clean up the look of embedded blocks.

But yes, there are definitely use cases that would benefit from a specialized plugin.

1 Like

Actually every text line has a number (even if hidden), so surely,if it were parsed, this could be used. Line instead of block should be okay.


My thoughts on that in another forum topic: Block reference

1 Like

huh! :thinking: Interesting approach! I think for those of use using a strict folder structure, there would be a hassle of finding a place to put these newly made files, but it sounds interesting. Though For longer strings of text, as you mentioned, there is the limitation imposed by the OS (for windows it’s 255), and the use of most special characters is out of the question. But I think it will do. At least the price of using a Database is probably too high of a price for having something more convenient.

1 Like

The problem with referencing a line number is that as soon as you add a line anywhere above it, the whole thing falls apart.

I’ve been entertaining the idea of plain text block referencing for a while now, and I believe that some ID has to be added to the referenced line. Maybe just a few characters.

1 Like

I think in theory it could be done by tracking, in the same way that Obsidian tracks and adjusts for name changes.

@macedotavares @Dor Indeed, I think the best plugins for this will do both instantiate a block reference with a few characters and then cache and track that instantiation.

If I were to make such a plugin, I would use something like ((double parentheses)) to declare a statement reference. The statement itself can then be the identifier. (This assumes such statements would be unique, which I think is safe.)

Adding a couple thoughts. I think we could get most of the way there with Aliases if there were a way to embed a Page or Header without actually displaying the page title or header (e.g. embed contents only) and to display the contents in-line instead of inside a box.


  • Make a file called
  • Type this out: [[blockRef123abc|Content I want to embed.]]
  • This would create a file called ‘’ linked to a line of text “Content I want to embed.”
  • Now I can manually add the text “Content I want to embed.” to the file ‘’.
  • Finally, I can embed this in another file with ![[blockRef123abc]]

The remaining problems are that the whole thing is in a box and that there’s a big “blockRef123abc” title above it.That should just be a display thing. Remove the title and display the content in-line with the rest of the note. We might even be able to do this with custom css? I’m not sure.

Now let’s modify this a bit:

  • Keep your file, but also make
  • Open and type the following:
# blockRef123abc
Content I want to embed.
  • Now, in another file, type: [[|Content I want to embed.]]

This works almost the same way as the first example with the same problems, except that, instead of creating a new markdown file for every single block you want to reference, you’re creating one additional file for each file that contains blocks you want to reference. The number of block reference files are, at most, going to equal the number of non-reference files in your vault instead of the total number of “blocks” that you want to reference.

Having gone through all that, I think a specialized syntax for creating a block is probably simpler (e.g. [[%abc123|Content I want to embed.]]. Though you’d probably need a way to generate a unique ID - at least unique per page, since you would probably do something like ![[BlockTest%abc123]] to embed it

The other problem I see is that any of these solutions would make the text pretty messy and difficult to read in edit mode.

We are able to do such thing by CSS. Many examples in the current CSS library.

I don’t like ‘problem(s)’ :wink:

I’ll be quoting a few posts from Block reference to summarize best practices found in that thread (which is a bit long).