SEP 17: Document Transclusion

A previous version of this proposal was titled Allow internal references to include automatic snippets.

The recent implementation of ✅ SEP 12: Reference documents by their URN/UUID represents the thin end of the wedge in my aim to make this an increasingly dynamic and self referential body of work. Being able to quickly reference

Syntax

Currently it is possible to reference another document with as few as 13 characters [](\!74534cff) (without the slash) and the build system will pick up that reference and fill in the right link target (slug) and link text (title).

This brevity should be preserved as far as possible so that the.

Considerations

While not an absolute prerequisite it seems sensible to implement document summaries before this proposal so that the included snippet is derived in a consistent and robust way, offering consistency rather than having potentially multiple code paths generating differing document summaries in the future.

I’m interested in expanding this proposal to support the transclusion, not just of snippets, but of entire documents within one another. One of the things I really like about the data model I’ve adopted for this site is the fact that almost everything is an atomic document, meaning that even if it ceases to reflect my thinking that document/those thoughts will continue to be preserved. The exception to this is in things like the /about page, or the blurb on the site homepage. If I make a change to the text of such documents, the old version is lost. I want instead to create these ‘hub’ type pages by transcluding one or more other fragments/flakes/documents into it. That way, when I want to, for example, change what’s written on my /about I can just replace the reference to the previous fragment with one to a new/updated one without anything of the previous being lost.