A proposal for rendering block references inline

With the work on Live preview (WYSIWIG) currently in process, I think this is a good time to discuss and propose a different design approach to how block references render in Obsidian. The reason I propose this design change now is that Live Preview is in beta. While more work is required to implement this design approach, it’s easier to make such a design change now while Live Preivw is in beta before the larger community begins to use it.

Summary of requested change

I am proposing that Obisidan change its approach to how block references are rendered. Instead of being rendered as new lines (HTML DIV’s) that they be made to be inline (HTML SPAN).


  • A block reference can be used inline of other text and the text flow continues without line breaks. Currently if we want this, we need a CSS hack
  • If we want a block reference to be on its own line, then we can make a new line.

Simply put, if block references are inline, we get the benefits of inline text and putting block references on their own line without having to use any CSS hacks. Two birds, one stone.

Detailed Description

The following is an example of how block references are rendered in Obsidian.

  • The first line “Hi I am a block” is a block of text with its block reference ID at the end.
  • This block ref is used in two places in the file, first in a paragraph with other text and then a second time on a line on its own.

Notice that no matter where I use the block reference, it is always forced to a new line.

However, other tools in the PKM space do not work this way with block references. The default is inline text flow. Let’s look at 3 competitors: Craft, Logseq and Roam.


Craft handles block references inline by default. Notice the same document used in the previous Obsidian example and how Craft renders it:

The block reference is rendered inline.

The benefit is I can control the text flow myself. If I want the block reference text to flow inline, then I can just put it into an existing paragraph. If I want it on its own line, then it will look like its own paragraph.

No CSS hacks and I get two styles of use from the same block references.


Here is Logseq, like Craft it also handles block references inline by default.


Here is Roam, like Logseq and Craft it also handles block references inline by default.



In conclusion, most PKM tools with block reference support handle them inline and I propose Obsidian adopts this behavior.

Block references are a very powerful tool, actually known for years for its potentional as transclusion. The current Obsidian approach isn’t consistent with other tools and it makes it harder for someone to migrate to Obsidian.

Inline block reference embeds allows us to include our thoughts in the stream of thought without creating extra formatting layers, when that may not be needed unless I want it to be that way. The distinction is subtle.

But once you have this in your workflow, your thoughts become much more reusable. Don’t get me wrong, what we have already gets us most of the way to this goal, but the implementation makes assumptions about what we want to do with it. Treating them as inline is less speculative about intention, requiring the user to be intentional with the desired results.

For these other tools, block references are considered a major feature. I don’t sense the Obsidian community considers it such a big deal, but I think this is due to the rendering implementation. Once rendering is handled consistently as with other tools, this is likely to become a more relevant and useful feature in Obsidian.


One must acknowledge that transclusion doesn’t work with all content. So the user still has to experiment with what they embed in other places. For example, if you have a table and you embed that table into a paragraph of text, the formatting is going to not look good and maybe not work. But those who have experience with block references learn where they work well and where they don’t.


I want to provide some practical use cases to support this proposal.

Task Management

Imagine you have content in a file such as this:

Paragraph 1 ^blockid1
Paragraph 2 ^blockid3
Paragraph 3 ^blockid3

Now you want to convert one of these paragraphs to a task? You add this to your Daily Notes Page:

  • [ ] Confirm facts in this paragraph ![[file^paragraph1]]

And this renders as

  • [ ] Confirm facts in stated in Paragraph 1

Bible Research and any other types of research based on other texts

You are using one of the bible research tools for Obsidian and you are making notes like this:

As our lord said at ![[Matthew05^v003]] we should be hungry for spiritual things.

renders as:

As our lord said at Matthew 5:3 Happy are those conscious of their spiritual need, since the Kingdom of the heavens belongs to them. we should be hungry for spirtual things.


Agreed. And it seems to be a very doeable change too, from DIV to SPAN. Or DIV “display: inline”? Transclusions are quite “bulky” as they are at the moment, would be really nice to have something sleek which can quickly fit in-text.


Thanks for taking the time to post this.


Pretty normal in Craft.
Obsidian should go for it.


Massive fan of this idea! Would be very very useful. Thanks for the write-up!


I think it also makes the reading experience a lot nicer.

1 Like

I like it. I support this implmentation.

1 Like

I support this idea as well. You have my vote

I like the inline idea as it is easier to use the text any where that I want vs it’s own line

1 Like

Thanks, this is so well explained. Inline block references would be a really useful feature.

1 Like

Agreed. I use block references a lot to rearrange notes for longer writing projects; inline referenced would make this process much smoother.

Very much YES! to inline block references, a subtle dashed line to let you know it’s an embed, and you are good to go!

Currently it takes too much effort to enable this via css snippets that have to be adjusted to the theme etc.

I would also vote for an option (toggle?) of ‘new line embeds’ to be somewhat more minimal (it adds a lot of padding…)

1 Like

I use transclusions a lot, and have had to use CSS hacks to make them look “natural”, i.e. part of the host text without a visual break.

I am now using Live Preview, and the way block references are rendered is as indented text with a golden frame around it and the link icon permanently visible. This makes it look very much out of place.

So, I have worked at hiding the frame and icon, only display the latter on hover of the block, and vertically aligning with the host text.

Issue: vertical alignment varies in practice from block to block or note to note, and in Preview vertical alignment is out.

So, yes, I think this is a brilliant proposal.


Great to read this proposal!
If I can give some kind of suggestions, I would go for an easy set of characters (like, for instance Roam does, but I don’t know any other PKM tool) to start block referencing. Right now typing [[^^whatever]] takes a century…


Adding in another vote for this proposal :slight_smile: This will make it far easier to build up sentences using multiple block refs visually. And it will also align with how many of the popular TfT tools handle block-refs. Thanks for the write up! :slight_smile:

1 Like

Yes, this would be very very useful. I am all for this proposal…

1 Like

Agreed! This would make block references much more useful

1 Like

Yes, it would be very useful for us as it would make reading more enjoyable.

1 Like

(+) :100: this will help smoothing writing flow without the need of CSS. Love it!


I love this idea

1 Like