Substitution is a function whereby, when an editor saves a page, an item in the wikicode is permanently replaced with its current value. In particular, a template can be substituted, as an alternative to transclusion. The difference is that when a template is substituted on a page, its appearance on that page will no longer be affected by later changes made to the template itself (as is the case in a transcluded template).
Generally speaking, templates are transcluded rather than substituted, although there are some that are specifically designed to be substituted (and may not work if transcluded). Some reasons for substituting templates include:
Time-dependent variables are substituted to make the rendered page independent of the time at which it is viewed. Substituting page-dependent variables makes the resulting wikitext independent of renaming of the page and of copying to another page.
For more detailed guidance, including lists of templates which should or should not be substituted, see Wikipedia:Substitution.
There may be whitespace between the opening braces and the "subst:". However it is recommended not to have any space or newlines immediately after the "subst:", as this will not work in every case.
Substitution is part of the process performed on saving a page, and causes the wikitext saved as a result of the edit to differ from the text which the user actually entered in the edit window. Other replacements performed during this process include expansion of links using the pipe trick, and replacement of multiple tildes with signatures and timestamps.
Clicking the "Show changes" button during editing shows the wikitext that will result after substitution and other immediate replacements are carried out. Clicking "Show preview" shows what the rendered page will look like after these replacements.
If a page substitutes itself (e.g. in the noinclude part of a template page) it substitutes the old version, as it was before the current edit.
If the expansion of a substituted template itself contains instances of the
subst: syntax, then the substitutions are performed recursively. However substitution is not automatically recursive – if a substituted template contains ordinary transclusions or variables and parser functions which are not explicitly substituted, then these will not be substituted.
safesubst: modifier is used in the code of templates which are designed to produce recursive substitution when substituted; but that are also intended to work when transcluded or simply to be viewed directly. Contrasted with using the
subst: modifier, such templates would break in such cases of transclusion (and possibly on direct viewing).
For details on how to implement this (in particular, how to prevent the substitution from being performed as soon as the template code is saved), see § Recursive substitution.
As mentioned above, substitution is not automatically recursive. So if a substituted template has code containing transclusions of other templates and parser functions, that code will be copied "as is" into the resulting wikitext – the transcluded items will not themselves be substituted.
To make substitution work recursively, you must include the
subst: syntax in the code of the calling template. However, you cannot do this by simply typing "subst:" within the template, as the substitution would then be performed as soon as the template is saved. There are two ways to work around this problem:
To ensure that the template will still work as intended if it is transcluded instead of substituted, use
safesubst: instead of
subst:. This also applies if the template is also to be viewed directly, on its own page (although in this case, if the first of the above methods is used, plain subst: will still work, as the includeonly tags will cause the parser to ignore the subst: on direct viewing).
To see what a template will produce when fully expanded, without the need to explicitly substitute all subtemplates etc., the Special:ExpandTemplates tool can be used.
Guided tours can make posts on behalf of users, such as automatically posting the contents of a wiki page onto a talk page. Unlike normal substitution or transclusion, however, this function of guided tours does not respect
<includeonly>...</includeonly> and similar markup. To make recursive substitution work via guided tour posting, you can use the Delaying Template:subst method described on Meta.
This is an example using the actual Template:Like, and a hypothetical Template:Foo. You are attempting to include the Template:Foo, and indirectly the Template:Like, on a third page through transclusion and substitution. Template:Like displays this symbol: Like
Usage of a template through
subst: does not automatically show up in page histories. Therefore, providing the line of wikitext containing "subst:" in the edit summary is especially useful.
Also, pages with a substituted template do not show up in backlinks, and the template does not appear in the list of transcluded templates on the edit page. The template could add pages to a category to track substitutions, but listing this category on a page may clutter the list of content-based categories the page is in. Also, comments outside noinclude tags are included in the wikitext. Thus a comment can be used to mention the template. Substitution of parameters does not work inside comments, but a workaround for this is to begin an intended comment with
<!<noinclude />-- so that it turns into a comment once transcluded.