Wikipedia:Transclusion costs and benefits

How substitution works

MediaWiki provides the subst: command, which simply substitutes one page within another. This is very different from transclusion, although the difference will usually be invisible on the first edit.

To substitute a page, use this code instead:

{{subst:SOMEPAGE}}

(The same syntax applies as in the case of transcluded pages.)

When you preview a page containing a substitution, you will still see the code in the edit box; you can change it if you like. But when you save the target page, the engine substitutes, or replaces, the code with whatever is on the source page. If you edit the target again, then you will see that the substitution code is gone; the content of the source page has replaced it directly.

The link from the target to the source is not merely broken; it does not exist at all. Now, if the source page changes, the target page will not change. The substituted content is frozen in time, in the form it had at the moment the page was saved.

Substitution and transclusion can be used together, and often this is a good idea. Instead of using double transclusion, you might substitute one page in another, then transclude that page in a target page. Or, you might find that a page transcludes another; you choose to substitute the transcluding page in a target, rather than force a double transclusion.

On the other hand, double transclusion can be very useful, and may be justified or even demanded in certain contexts. Each case is different, and can only be decided after careful, informed consideration of the technical and social situation.

Tagging

A very common use of templates is to "tag" a page—to insert on it some snippet of text, often boxed, often seen at the very top or bottom of a page. A tag does not contain content, but metacontent: information about the page itself.

For example, {{FAC}} inserts the following tag:

This article is a current featured article candidate. A featured article should exemplify Wikipedia's very best work, and is therefore expected to meet several criteria. Please feel free to leave comments.

There are hundreds of tags, each with a different function, many transcluded onto hundreds of pages. Thus tags represent a non-negligible fraction of server resources devoted to transclusion (conversely, tags are, by design pretty lightweight - offsetting the number of transclusions). Many tags include category references, which automatically include pages on which they are transcluded within a category.

Article pages are rarely transcluded, so tagging them presents few problems—the same goes for Talk pages, Wikipedia namespace pages, and indeed most pages. When a page is so tagged, the tag appears only in that one place; if it refers to "this page", it is clear what is meant.

However, Template namespace pages are intended to be transcluded and substituted, so tagging them—for any reason—is problematic.

Whatever tag is applied to a template page is applied to every target where the template is used. If the tagged template is substituted, then the transclusion code of the tag will "fall out loose" into the markup of the target page—including any category reference. This results in such inanity as users being nominated for deletion. Note that modern template design has largely obviated this problem.
No matter whether the tagged template is transcluded or substituted, it may be visible on the target for all to see. This may be embarrassing, destructive, annoying, or merely appear childish. Depending on the text of the template so tagged, it may be quite impossible to see, when looking at the target, what has been tagged. In general, the casual reader will have no idea what is meant.
Any text or markup may be transcluded, within very broad bounds; and some templates are highly technical, especially those intended as sub- or master templates, with nested parameter calls, or used to manage other templates. Altering even a single character within such a template may not only cause it to break, but cause a cascade of broken templates and damaged pages. Tagging such a template almost guarantees it will no longer function as intended.
Tagging templates is a class of double transclusion, at the least; if either tag or template are already involved in double transclusion, the result—as seen on a target page—may be triple or quadruple transclusion. All the costs of double transclusion apply in these cases, and may be intensified.

There are cases in which tagging a template may be less destructive; however, it is very difficult to isolate them—to ensure that a tag will cause no problems.

Therefore: Most tags should not be placed on most Template namespace page bodies. If a certain tag seems to apply to a template, there are various options: sometimes the tag can be placed on its associated Talk page or /doc page (if any), or it can be <noinclude>d onto the template. Some tags, such as {{tfd}}, are specifically designed to be visibly included on templates in order to draw editorial attention.

Other kinds of inclusion

Other types of markup and engine function also cause content to be included in a rendered page, similar in effect to transclusion or substitution:

Images are transcluded in rendered pages.
Signatures and datestamps (generated with multiple tildes) are substituted in pages when saved.
If the signature markup contains a template call, the template call is substituted and the template contents transcluded on each appearance of the sig. If the signature markup contains an image call, the image is transcluded on each appearance. Template calls are currently (2011) prevented from being included in signatures by the software configuration.
The main site logo Image:Wiki.png is on every page rendered with some skins. All pages transclude some standard links and text.

How substitution works

Tagging

Other kinds of inclusion

See also