Drafts - Transcluding Drafts

Over the past year or two, transclusion is a topic that has come up several times in the Drafts forum, particularly in the context of other apps for personal knowledge management (PKM), such as Obsidian, Roam Research and Logseq to name just a few. In this post I’m going to talk a little about what transclusion is and how you can include some of the functionality in Drafts.

What is Transclusion?

Transclusion is a technical term for the ‘transparent inclusion’ of one piece of information within another, particularly in relation to computer files and documents. It follows a similar idea to code libraries used by developers in that it gives you a single copy of something for maintenance purposes, but that source copy may be used in other places.

This sort of structure gives you efficiency through embedded re-use and through minimised maintenance.

What is the Difference to Using Boilerplate Text?

You may be wondering if templating and boilerplate insertion tools such as TextExpander fulfil the same purpose? After all, they provide a single source that can be reused and inserted in other content. The answer is no, but they both have their place.

Boilerplate insertion is good for content that is going to be a snapshot for a point in time. The content is not intended to change on an ongoing basis. Transclusion on the other hand if suited to content that can potentially be updated on an ongoing basis. So an invoice is probably best suited to being built from a boilerplate template as it should not change once generated. But, the template itself, may be well suited to transclusion, to ensure that it always contains the very latest information.

Many tools such as TextExpander kind of implement this in that you can nest boilerplate text, but always with the idea of producing boilerplate output. Transclusion, however, forces any update to content that has transcluded to be reflected in those transclusions.

A better example of a transclusion might be some part of a business process that is used in several places. For example, steps to engage a cycle courier. This could be part of many separate process checklists. If this is transcluded rather than inserted as boilerplate text, when the cycle courier details are changed, all process documents that use this information automatically update with the latest information.

Many people like to use transclusion simply as a way of breaking down content as they write large documents (e.g. a novel or technical paper), or as a way to reuse common elements multiple times in a single document (a data placeholder like you might use in a mail merge).

Drafts - Preview Transclusion

Greg Pierce, the developer of Drafts, created a Drafts action called Transclude > Preview, that you can download from the Drafts Directory. The action creates an HTML-based preview of the current Draft (assumed to be some flavour of Markdown), but as part of the processing of the draft for previewing, the action searches for any wiki-style cross-links to other drafts. For any such links, the preview substitutes in the content of those other drafts at the relevant point.

For example, let’s define three drafts to use to demonstrate this action:

# Primary Draft

This is the draft that I will use as my working draft, and I'll link to other drafts from within it.

First of all I'll link in [[Secondary Draft One]].

## Then...
[[Secondary Draft Two]]

## And for good measure...
[[Secondary Draft One]] again.

# Secondary Draft One
I am the **first** draft for inclusion

# Secondary Draft Two
- I am  
- the *second* draft  
- for inclusion.

Using the Preview action from the standard Basic action group, the resulting preview looks like this.

When using the Transclude > Preview action, the preview then becomes this.

Note that the title (first line) is included in this. Sometimes you may want to include drafts, but not have to have matching titles. There is a cross-link syntax based on draft UUID. We can create an additional draft like this.

I am ~~secondary draft three~~.

Then include that into our primary draft; the UUID of the above draft being 1A2DDD24-A5C6-4D78-A7C1-4084A4B40100.

# Primary Draft

This is the draft that I will use as my working draft, and I'll link to other drafts from within it.

First of all I'll link in [[Secondary Draft One]].

## Then...
[[Secondary Draft Two]]

## And for good measure...
[[Secondary Draft One]] again.

Now let's include [[u:1A2DDD24-A5C6-4D78-A7C1-4084A4B40100]]

Unfortunately the Transclude > Preview action dopes not support these types of cross-links. However, my exploded preview action does support transclusion of this sort of cross-link (as well as various other features).

In addition, the ThoughtAsylum action group (currently the second most popular action group in the Drafts Directory) also has a helper action called TAD-Prime Preview that provides support for even more preview options.

This prime preview action supports custom CSS, draft transclusion, draft template tag expansion, base64 encoded images, syntax highlighting, mermaid diagram blocks, Font-Awesome, Drafts/GitHub style check box conversion, critic strikethrough (GFM rendering only), and both MutiMarkdown and GitHub Flavour Markdown rendering options. It should not be run directly, and will issue an error if it is, but rather included from another action which sets the CSS tag (css) and the rendering engine template (engine) as MultiMarkdown (MMD), or GitHub Flavour Markdown (GFM).

As a helper action, it must be called by other actions that set up the option for the rendering engine. The ThoughtAsylum Writing Action Group includes TAD-Prime Preview MMD and TAD-Prime Preview GFM actions supporting MultiMarkdown and Github Flavour Markdown rendering respectively.

But, this means it will also support things like strikethrough that the exploded markdown preview action did not.

Drafts - Editor Transclusion

Drafts does not currently have a native way to transclude content in the editor, but in September 2020 I released some actions in the ThoughtAsylum Action Groups for Drafts that allows draft content to be embedded, and importantly, refreshed; thus reproducing the core functionality of transclusion - just more semi-transparent than transparent inclusion.

There are three actions in the ThoughtAsylum - Management action group that were created to support this functionality.

TAD-Embed a Draft

This action is used to insert the content of another draft into the current draft. When it is run, you are prompted with a searchable selection list from which you can choose a draft to insert. Upon insertion, the content of that draft is placed at the current cursor position of the current draft. It is also wrapped in some HTML comments that define the draft that has been embedded.

# Primary Embedding Draft

<!-- EMBED : [[u:5D28C186-D4F4-417F-95B2-F806D9567926]] -->

# Secondary Draft One
I am the **first** draft for inclusion

<!-- [[u:5D28C186-D4F4-417F-95B2-F806D9567926]] : EMBED -->

<!-- EMBED : [[u:FF72DCB3-A3B9-476E-9E8E-8370B05AA55A]] -->

# Secondary Draft Two
- I am  
- the *second* draft  
- for inclusion.
<!-- [[u:FF72DCB3-A3B9-476E-9E8E-8370B05AA55A]] : EMBED -->

<!-- EMBED : [[u:1A2DDD24-A5C6-4D78-A7C1-4084A4B40100]] -->

I am ~~secondary draft three~~.
<!-- [[u:1A2DDD24-A5C6-4D78-A7C1-4084A4B40100]] : EMBED -->

Because the comments are defined in a cross-link format, they will actually allow you to navigate to those drafts within Drafts as you can see from this screenshot.

Because the content is embedded, standard basic preview action, including the built-in live preview functionality or even Marked2 preview will render the content as it would for any other draft. The HTML comments are valid Markdown, and pass over as HTML comments, and so are not displayed in the preview.

TAD-Refresh Embeds of/in this Draft

The other two actions will update embedded content in drafts, but they come at it from different ends of the embed relationship.

If you are updating a draft that is the source draft (i.e., it is embedded in other drafts), running the TAD-Refresh Embeds of this Draft will locate the drafts containing the EMBED comments and update the content between the matched comments to be the latest content of the current draft.

If you are updating a draft that has other drafts embedded in it, running the TAD-Refresh Embeds in this Draft will scan the current draft for EMBED comments. For each embed section, the content will be retrieved from the source draft, and the content of the current draft will be updated.

Conclusion

Transclusion is an approach that can provide significant benefits in terms of efficiency, and it seems to be slowly becoming a more commonplace requirement in text processing and note taking tools. Even though Drafts does not support it natively, transclusion options can be provided through the application of actions. This versatility is what makes Drafts one of the most useful tools I use.