Wikipedia:Transclusion Costs And Benefits

This is an essay, a collection of thoughts from contributors, not a decree from on high. It’s not policy, it’s not a guideline, it’s just… an idea someone had. And like most ideas, it hasn't been run through the community mill enough to be universally accepted. Some essays are so obvious they become de facto rules, others are fringe theories whispered in dark corners. This one? It’s somewhere in the murky middle.

Shortcut • WP:TCB

There’s a persistent, low-grade anxiety that the template system, this neat little trick of transclusion, isn’t always used with the wisdom it deserves. Transclusion itself is simple enough—a concept so basic it feels almost insulting to explain. But like any powerful tool, its consequences can ripple outwards in ways that aren’t immediately obvious, especially if you’re not fluent in the arcane language of MediaWiki. Templates streamline countless tasks, yes, but they also come with a price tag. This isn't just about the occasional glitch; it’s about the very real cost in machine resources, which is why the software itself imposes template limits. Even within those boundaries, there are subtler expenses. This piece aims to dissect those costs, weigh them against the benefits, and perhaps, just perhaps, offer a sliver of clarity.

Transclusion Background

The mechanics are straightforward. To pull content from one page, say, a source page, and embed it into another, a target page, within the same MediaWiki project (like this very English Wikipedia), you employ the syntax {{SOURCEPAGE}}.

When the software encounters {{SOURCEPAGE}} on a target page, it doesn't just link to it; it retrieves and embeds the entire content of SOURCEPAGE (which is typically a template, hence Template:SOURCEPAGE) directly into the target page at that precise spot.

Example

Imagine target pages labeled A, P, and Q. And let's say page B is our source.

If you were to write {{B}} on page A, the content of page B – let’s pretend it’s just the word "foo" for simplicity – would materialize on page A exactly where {{B}} was written. This isn't a separate box or a highlighted snippet; it’s integrated seamlessly into the text of page A. Think of it as a live wire, not a framed picture.

How It Works

The essence of transclusion is the creation of a dynamic, ‘live’ link. When you transclude content, you’re not just copying it; you’re creating a persistent connection. Any change made to the source page automatically propagates to every target page that uses it.

Consider this: you create a template detailing an upcoming Wikimedia event. You then transclude this template onto the talk pages of, say, fifty editors you want to invite. If the event venue changes, or the time is shifted, you update the single source template, and instantly, those fifty talk pages reflect the updated information. Effortless, isn't it? Almost too effortless.

Edit Source Pages With Caution

This power, however, demands a certain reverence. Editing a source page is akin to pulling a lever that affects a multitude of interconnected systems. If that source page itself transcludes content from other source pages, your edits can trigger a domino effect. A poorly judged change can cascade, breaking not only the immediate source page but also all the target pages that rely on it, and any subsequent pages that rely on those. This phenomenon, often termed ‘breakage,’ underscores the importance of ensuring any updates preserve the structural integrity of the transcluded content across the entire network. The Main Page, for instance, is a colossal entity, weaving together content from numerous embeddable source pages like Wikipedia:Today's featured list. Messing with those foundational pieces is not for the faint of heart.

Costs and Benefits

Further information: H:TRANSDRAWBACKS

Transclusion, like any tool forged by human hands, possesses both utility and inherent drawbacks. The precise calculus of these costs and benefits is a perpetually shifting landscape, heavily influenced by the intelligence—or lack thereof—applied to its design and implementation. To claim absolute neutrality on this matter would be an exercise in self-deception. Both sides of the equation are largely subjective, notoriously difficult to quantify.

Social

There's a palpable social cost associated with transclusion: the cumulative, long-term risk that a transcluded template might fall victim to vandalism. Imagine a widely used template’s content being replaced with utter nonsense. That gibberish then momentarily contaminates every single page where that template is embedded—just as any edit would. It’s an added strain on the system, much like any edit. To mitigate this, the most heavily trafficked templates are typically protected, often with the reassuring visual cue of this icon, to deter malicious interference.

On the flip side, reversing template vandalism is as simple as its commission. The offending text is removed, and the previous content is reinstated. This, of course, still imposes a burden on the engine.

While consolidating large amounts of text into a single template, transcluded across numerous pages, offers some savings in storage, the direct benefits to the machine from transclusion itself are generally minimal.

Users, however, often find transclusion immensely useful, sometimes in ways that were entirely unanticipated. Virtually any form of text, markup, HTML, or CSS code can be transcluded. If that element appears in multiple locations, templates drastically reduce manual labor. More than that, by minimizing repetitive typing and the errors that inevitably accompany it, templates alleviate ‘Wikistress' and reduce the need for constant, tedious janitorial work.

Comparison

A fundamental tenet of effective design, graphic or otherwise, is standardization. If a particular list format is deemed desirable across several pages, then logically, all such lists should conform to that same presentation. Even if the specific items within the lists vary, a uniform appearance offers a distinct advantage.

From a purely technical standpoint, this standardization isn't strictly necessary; the engine functions perfectly well with disparate list formats. However, a consistent appearance lends a crucial air of professionalism to the human reader's experience. Furthermore, modifications to the mere layout of these lists can be implemented across all instances simultaneously by altering the central template, rather than painstakingly editing each individual page.

The same principle applies to elements like the Wikipedia logo and essential site navigation controls. These are transcluded onto every page to ensure a cohesive look and feel across millions of articles. Updating the logo, navigation, or other site-wide elements can be managed from a single point, the effects rippling out to every page. While this incurs a rendering cost for each page, the social benefit of maintaining this uniformity demonstrably outweighs the resource expenditure.

Double Transclusion

Since virtually any page can be transcluded, what prevents us from transcluding a page within another, and then transcluding that resulting page within a third? Nothing. We can.

There are complex templates, master templates, designed to incorporate other subtemplates. When master template B is transcluded into target page A, it can, in turn, pull in subtemplate C.

Because both links are ‘live,’ an edit to the subtemplate C will automatically update page B, and consequently, page A. This chain can extend further: page C might transclude page D. In this scenario, the content on page A becomes an instance of triple transclusion. An edit to page D would alter page C, which in turn alters page B, which finally alters page A. It’s a veritable cascade.

Geometric Effect of Multiple Transclusion

The costs and benefits associated with double transclusion escalate geometrically. Consider a template X, transcluded into five other templates. Each of those five templates is then transcluded onto five target pages. Template X, therefore, is doubly transcluded onto twenty-five pages. An edit to X impacts a total of thirty-one pages: X itself, the five intermediate templates, and the twenty-five final target pages.

There’s no inherent limit to the number of targets a template can affect, nor to the depth of transclusion. This means that template X could be doubly or triply transcluded across hundreds, thousands, or even millions of pages. Consequently, double transclusion is an extraordinarily potent technique, and its very existence has become a point of contention. [ clarification needed ]

How Substitution Works

The MediaWiki software offers an alternative mechanism: the subst: command, which performs a direct substitution of one page's content within another. This is fundamentally different from transclusion, though the distinction might be imperceptible during the initial editing phase.

To substitute a page, you use this syntax:

{{subst:SOMEPAGE}}

The syntax mirrors that of transclusion.

When you preview a page containing a substitution, the {{subst:SOMEPAGE}} code remains visible in the edit box, allowing for further modification. However, upon saving the target page, the software executes the substitution, replacing the code with the actual content of the source page. If you revisit the target page for editing, you’ll observe that the {{subst:SOMEPAGE}} code is entirely gone; it has been permanently replaced by the substituted content.

Crucially, the dynamic link between the target and the source is not merely broken; it ceases to exist altogether. Consequently, if the source page is subsequently altered, the target page remains entirely unaffected. The substituted content is effectively frozen in time, preserving its state from the moment the target page was last saved.

Substitution and transclusion can be combined, and often, this is a wise decision. Instead of resorting to double transclusion, one might substitute page A into page B, and then transclude page B into the ultimate target page C. Alternatively, if page B already transcludes page A, you might choose to substitute page B into target page C, rather than forcing a deeper level of transclusion.

Conversely, double transclusion can be immensely beneficial and, in certain specific contexts, may be entirely justified or even mandated. Each situation demands careful, informed consideration of both the technical intricacies and the social dynamics at play.

Tagging

A highly prevalent application of templates involves "tagging" a page—inserting a snippet of text, often presented within a box, typically positioned at the top or bottom of the page. A tag doesn't convey content in the traditional sense; rather, it’s metacontent: information about the page itself. An example of this is {{FAC}}.

There are hundreds, if not thousands, of such tags, each fulfilling a distinct function, and many are transcluded onto countless pages. Consequently, tags represent a significant, non-trivial portion of the server resources allocated to transclusion. (Conversely, tags are, by design, quite lightweight, which helps to offset the sheer volume of their transclusions.) A substantial number of tags incorporate category references, automatically assigning the pages they are transcluded onto to specific categories.

Article pages themselves are seldom transcluded, so tagging them typically presents minimal issues. The same applies to Talk pages, pages within the Wikipedia namespace, and indeed, most other page types. When such a page is tagged, the tag appears in its designated location; if it contains a reference to "this page," the context is usually unambiguous.

However, pages within the Template namespace are specifically designed for transclusion and substitution. Tagging these pages—for whatever reason—introduces a host of potential complications:

Any tag applied directly to a template page will invariably appear on every target page where that template is used. Should the tagged template subsequently be substituted, the transclusion code of the tag will be "dropped loose" into the markup of the target page, potentially including its category reference. This can lead to absurd outcomes, such as users being nominated for deletion simply because a tag was applied to a template they used. It's worth noting that modern template design has largely circumvented this particular issue.
Regardless of whether the tagged template is transcluded or substituted, the tag itself may become visible on the target page, accessible to all. This can be embarrassing, disruptive, irritating, or simply appear amateurish. Depending on the specific wording of the tagged template, it might even be entirely unclear, when viewing the target page, what exactly has been tagged. For the casual reader, the meaning is often completely obscure.
While the bounds are broad, virtually any text or markup can be transcluded. Some templates are highly sophisticated, particularly those intended for use as sub- or master templates, featuring nested parameter calls or managing other templates. Altering even a single character within such a template could not only cause it to break but could trigger a cascade of broken templates and corrupted pages. Tagging such a template almost guarantees its intended functionality will be compromised.
Tagging a template constitutes, at minimum, a form of double transclusion. If either the tag or the template is already involved in a double transclusion, the resulting display on a target page could represent triple or even quadruple transclusion. All the inherent costs associated with double transclusion apply here, and they can be significantly amplified.

There are rare instances where tagging a template might prove less destructive. However, isolating these specific cases and guaranteeing that a tag will cause no adverse effects is exceedingly difficult.

Therefore, the general rule holds: Most tags should not be placed directly within the body of most Template namespace pages. If a particular tag seems relevant to a template, several alternative options exist: the tag can sometimes be placed on the associated Talk page or /doc page (if any). Alternatively, it can be enclosed within <noinclude> tags on the template itself. Certain tags, such as {{tfd}}, are intentionally designed for visible inclusion on templates to attract editorial attention.

Other Kinds of Inclusion

Beyond transclusion and substitution, other Wiki markup elements and software functions achieve a similar effect of incorporating content into a rendered page:

Images are inherently transcluded into the pages where they are displayed.
Signatures and datestamps, generated using multiple tildes, are substituted into pages at the moment of saving. If the signature markup includes a template call, that template is substituted, and its contents transcluded for each instance of the signature. Similarly, if the signature markup contains an image call, the image is transcluded with each appearance. Currently (as of 2011), software configuration prevents template calls from being included directly within signatures.
The primary site logo is rendered on every page, irrespective of the skin used. Furthermore, all pages transclude a standard set of navigational links and accompanying text.