Transclusion to sections?


I am one of those who enjoy working with an Obsidian vault for journaling and developing thoughts.

Somehow Obsidian helped to free myself from the vast amount of data and options in Devonthink – which make Devonthink great though. And being able to work on the vault from within Devonthink with the vault indexed is great.

One option I became to value highly is transclusion of section in files with the syntax ![[filename-without-extension#section-name]].

Linking to sections with a hashtag is a widely used practice in HTML, Markdown etc., so I think it is safe to say, it is close to a standard.

I would love to see the option to link / transclude to sections in other Markdown files in the future.

I’m not sure what exactly you are asking for here. Firstly, linking to an anchor in an HTML document has nothing to do with transclusion. HTML does not know anything about transclusion.

Secondly, what is a “section” in a file? There’s a section element in HTML, but that is not related to anchors and links per se. There are no “sections” in a MD document (at least not that I know of). I guess that you might want to somehow™ link to a title element. While that is defined in (e.g.) Githubs MD dialect, it only works for in-document titles there, not across documents. I’ve not found any example for transclusion (!) of “sections” in MD dialects (except maybe that invented by Obsidian, that is). And I wouldn’t know what exactly it is that should be transcluded in that case (i.e. copied verbatim). The title and the following text before the next title? Before any next title or just one of the same level?

I think the specification is not very clear, and there’s no argument for inventing another MD thingy (and create another dialect in the process).

Thanks for taking care. I thought my sentences were clear though. I did not ask for transclusion in an HTML document or from an HTML document but just mentioned the hashtag as a common means to adress a section in a file.

Furthermore I am not asking for creating another MD thingy or dialect, but when formulating the feature request hinted to solutions that exist, that seem sensible to me and are related to similar usages in similar cases.

Furthermore, I think it is self explaining that, if a section of level h2 is adressed, the transclusion covers the h2 section including lower hierarchies.

Finally, because HTML uses the term “section” in a certain sense, I do not think that it is forbidden or stupid or whatsoever to use the term in a similar sense in a slightly different context. I cannot remember to have been educated in that way on the Pandoc mailing list or elsewhere.

It may well be that there is not usecase for you, but there are certainly for me. Summarizing parts of structurally identical documents in another document that only focusses on these parts e.g. are reasonable scenarios.


I can see a use case for linking to markdown headings. But:

Surely that is a little challenging? What happens with a document like this?


Transclusion might take the first h2 and h3 (if that were possible) but would then presumably trip up when it encounters the second h1.

I’m not arguing against you but merely indicating that it could be rather more complex than we might think.



I’m not arguing against your use case. But I do not believe that „section transclusion“ is „widely used“. And if it’s not, there’s no generally agreed syntax or semantics. Which in turn means that DT would have to introduce a new piece of syntax and semantics that work only in itself and possibly Obsidian.

That’s not the way standards should go. In my opinion.

1 Like


Thanks for the considerate response.

Yes, I also think that there are challenges, and therefore I do not suggest every idea that comes to my mind, I think you understand my suggestion that way.

As for the limits of transclusion, I thought of it from the beginning of a section down to the beginning of another section of the same or a higher level. In your example, a transclusion starting at the first h2 would include the h3 part and finish with the second h2 part, and the second h2 would finish with the following h1 part.

Of course, other rules may apply like, transclusions only covering the part down to another section of whatever level starts e.g…


Got it. Think the same way often, but not in this case.

Yes, of course. However, having experienced one or two different markdown apps I tend more and more to the view that I much prefer to stick to apps which honour some form of standard markdown (although I accept there are even different flavours of that). That was a key reason I stopped trialling and experimenting with Obsidian.



That is interesting. I have used MultiMarkdown and Pandoc, Github flavor, and I prefer to stick with standards that cover all of them. Therefore, after trying some plugins like dataview etc. in Obsidian, I have cut most of them off. I use Obsidian only as a part for in my Devonthink database because some features are really nice (for creating stuff and journaling), but I also wonder whether after all, Devonthink could take this over again. It is certainly alot more versatile and powerful.



Yes: I really like the way DEVONthink honours markdown standards and yet is so versatile. The only other markdown app I now use is Typora—which also seems quite strict about use of standards.


1 Like


Hard to say whether translusion at the section level would add value, from my perspective. I think it might, but would have to experiment (if it ever were to become a feature in DevonThink).

What I wanted to point out: It is possible to transclude items at multiple levels. So if document A contains transcluded contents from a document B, then adding a transclusion link to document A into another document would lead to it containing the contents from all three.

A workaround could therefore be to use the current transclusion functionality and be very “atomic”, i.e. focused and precise regarding the contents in each individual document, instead of using lots of headings and sections. Then using transclusion at multiple levels.

Yes, atomic notes would be a solution for the technical problem. This would mean to create groups or folders for every document that was one in the beginning. I do not think that the freedom of writing in a structured document will get lost with this approach.

To be more clear about the use case, I use the transcclusion of sections in structured descriptions of items or contexts, or parts of journals that will be summarized in a weekly summary. I can imagine of transclusion of sections from longer documents as well, could be very useful.

After all, developers may understand how much work such a development would be and how well an implementation can be adapted to potential standards.


after the discussion from yesterday I would like to return the topic to my original intention:

Developing an option for transclusion of sections of Markdown documents in other markdown documents.

As an example for implementation I mentioned the implementation in Obsidian.

As an example for usage I mentioned transclusion of parts of structured documents in another document that collects only these bits of information, or just writing longer documents with citations from other longer documents.

Hoping that my intention did not get lost,