Optimized handling of transclusion links that are no longer valid


I use transclusion a lot.

Inevitably, at times I will delete a Markdown note that has been transcluded.

In the transclusion document, this leads to the link being displayed in the preview instead of the transcluded item’s contents (which are no longer available). In the editor, the link looks the same whether it is valid or not.


  • Invalid transclusion links should not appear in preview at all.
  • Invalid transclusion links should be highlighted in a different color in edit mode to alert users and allow them to correct/replace them.

Thanks for considering.

What’s your use case, especially considering you often delete transcluded files?

If one of the transcluded notes has been deleted, it leads to a broken link in the transclusion document.

It would be easier to update these documents (I.e. replace or delete broken links), if they were more discernible in edit mode.

And also, broken transclusion links would no longer add clutter to the preview (where they do not add value).

Understood but my question still stands: What’s your use case, especially considering you often delete transcluded files?

I’m not quite clear on what kind of additional information you’re looking for, to be honest.

Since I use transclusion documents for topic-specific reviews of various kinds, I wish them to be up to date (hence the need to replace and/or remove broken links). And if I have not yet done the updating, then I would prefer broken links not to show in preview, as they impede readability.

That is my use case. Please specify what piece of info is missing

for topic-specific reviews of various kinds

Can you provide info on what this means, i.e., what you’re doing?
Perhaps you’re doing something unusual or perhaps you’re doing something that others may also run into the same issue.

In my use, there are two scenarios related to transclusion:

  1. Automatic transclusion of certain DT groups’ markdown notes via a smart rule script.
  2. Manual transclusion of markdown notes that are in different DT groups

The suggestions above pertain to the second scenario only, because in the first one any deleted markdown notes will automatically no longer show up in the transclusion document.

I use the item link in manual transclusions, i.e. {{x-devonthink-item://0C2D9BF4-4B33-47D6-BAA3-32E8368BE402}}.

While I’m not sure this is relevant to the feature request, I will indulge you @BLUEFROG and go into what topic-specific review means:

  • I have a Zettelkasten with various atomic notes that are cross-linked to each other in TheBrain. These Markdown attachments are indexed in DevonThink, where the hierarchy of groups from TheBrain is mirrored. The Zettelkasten can evolve quite a lot, hence the occasional deletion of certain Markdown attachments.
  • While the Zettelkasten’s main benefit consists of the non-linear visual connections across topic areas, I also like to do “linear” reviews for specific topics. This is what automatic transclusion of group contents allows me to do.
  • I also find it useful to create a manual transclusion of items across topic areas in DevonThink to create collections that are situationally relevant. For example, I created such a collection for those insights that are most applicable to current projects that I’m working towards. While these are across topic areas, just as the insights in the Zettelkasten, the benefit is that everything is in one document. This document can then be opened in VoiceDream, which provides high-quality text-to-speech and enables audio reviews on the go.
1 Like

Thanks. Useful (and relevant) indeed, especially if people are using a Zettelkasten system in the same way.

1 Like

The current behaviour is actually intended to show that there’s a broken transclusion. Skipping such transclusions would remove this benefit.

I understand.
Following that logic, wouldn’t raising awareness of the broken link be even more useful in edit mode where something can be done about it…? Here, however, the broken link looks just like the other ones.

Seems like this could be resolved with scripting. A script to search through markdown files and return links that point to non-existing records. Performance would depend on the number of files in question I guess.

While that is no technical problem, it might be a real performance hog: speed depending not only on the number of files but also on their size.

You’d have to get the plaintext of every MD file, find all the links in it, identify those only referring to local resources (as opposed to, for example, HTML documents on the web). And then someone would have to check if the resources referenced by the links are still available.

I tried something similar once in the context of the Alfred workflows for DT (ie scan a considerable number of files for strings), and it was so slow as to be unusable.

Wikis can possibly do what the OP wants. But they’re designed for this kind of document management. DT is far more general, which also means that it does not provide all the bells and whistles of specialized apps.

Yeah, it’d depend on how many files we’re talking and how often this script would be wanted to run.

Interesting idea to use a script.
If this was a smart rule script then it would probably suffice to run it once per hour at maximum. So perhaps the temporary performance hit, if any, would be worth it.

I can see how real-time updating might be resource-intensive. It’s being done for all kinds of other things in DT though, from incoming links entries to wiki links, etc. I wonder if this would be a showstopper, IF it is determined that the feature itself would add value to other users aside from myself.

Thinking about this more, the ideal solution, script-wise, would be to catch unwanted files as they are deleted. In other words, whenever a markdown file gets deleted, a script searches for and modifies any reference to it in other files.

Unfortunately, there is no ‘On deletion’ smart rule trigger or anything like that, as far as I know.

Another trick might be, instead of deleting these files, tag them as ‘deleteme’ or something and let the smart rule do it.

1 Like

This would be, in my opinion, the worst possible approach – given that the number of documents can be huge. If the transclusion links are reflected in the incomingReference property, one would

  • have to check every MD record’s property for a reference to the record being deleted
  • update the content of a matching record by … doing what exactly? Remove the link? Leave it there and add a warning? Remove it and leave a warning?

Apart from that: I’m not sure that there even is a delete record action in DT. AFAIK, there’s only move to trash. And something that has been moved to the trash can be restored (that being the idea of a trash in the first place). Now, the links are deleted and the item is restored. Difficult to restore the links, I guess.

There is of course such a script command (and the same smart rule action) :slight_smile:

1 Like

Unless I’m misunderstanding the issue, the transclusion link is just a UUID in plain text, wrapped in a special syntax. If you know the UUID in question, you can just use the search command to return every record whose file contains that string. Should take fractions of a second because it’s utilising the main DEVONthink search engine, not AppleScript per se.

Hidden preference IndexRawMarkdownSource needs to be enabled.


Good point thanks.