Template:Documentation/doc

Not to be confused with Template:Documentation subpage.

The {{Documentation}} template is used to contain and/or organize the available information about a template's intended functions and methods of operation, along with sufficient instructions for unfamiliar editors to be able to make use of it without issue in the most common foreseeable circumstances. This is typically done by creating a /doc subpage for the template. When necessary, however, it can also be configured to load the content from other pages or be directly supplied by using parameters.

This template has two parts: the big "documentation box" that presents the content beneath a toolbar (the heading and [view][edit][history][purge] links), and the smaller "link box" that shows metadata about the documentation alongside the sandbox and testcases links.

Usage

Standard behavior

Normally, the template is used without parameters and is placed inside <noinclude>…</noinclude> at the bottom of the template page (see the § Placement and tags section below for more information):

<!-- The last line of the template code --><noinclude>
{{Documentation}}<!-- Add categories to the /doc subpage instead, please. Thank you. --></noinclude>

Transcluding a different page

To transclude a different page other than the /doc subpage, simply provide it as the first unnamed/positional parameter, or as the value to the named parameter |1=, like this:

<!-- The last line of the template code --><noinclude>
{{Documentation|Template:Some other page/doc}}<!-- Add categories to the /doc subpage instead, please. Thank you. --></noinclude>

Note that when loading the documentation from a page other than the local /doc subpage, it becomes tricky to manage category inclusions.

Inline documentation

The documentation can also be placed directly in the page where this template is used by supplying it to the |content= parameter, as seen below.

<!-- The last line of the template code --><noinclude>
{{Documentation|content=
<!-- Template documentation content goes here -->
}}<!-- Add categories to the /doc subpage instead, please. Thank you. --></noinclude>

When using this parameter, the toolbar will not be shown, however the /doc subpage in the link box will still appear if it exists.

Also note that when both the |1= and |content= parameters are defined, |content= takes precedence and is always shown in the documentation box.

Custom headings

The heading in the documentation box changes depending on the namespace of the page on which it is transcluded. See the below list for the default text in each namespace:

Namespace	Heading
Template	Template documentation
Module	Module documentation
All others	Documentation

To customize the heading, simply define the |heading= parameter with the value you want to use instead, such as {{Documentation|heading=Infobox documentation}}.

Note that if the heading parameter is present but undefined (like {{Documentation|heading=}}), there will be no heading shown alongside the toolbar.

The |heading-style= parameter can be fed optional declarations, like {{Documentation|heading-style=color: red; font-size: 1.5em;}}. Note that you should not enclose values for this parameter in quotation marks " " and always terminate the final declaration with a semicolon ;.

Customizing the link box

To customize the link box, simply define a value for the |link box= parameter with the text you wish to replace it with, like {{Documentation|link box=The above documentation is automatically generated from [[Template:Foo]]}}.

To hide the link box altogether, simply define it as |link box=off.

Full syntax

/doc subpage

{{Documentation
 | heading       = 
 | heading-style = 
 | link box      = 
}}

Any other page

{{Documentation|[Name of documentation page]
 | heading       = 
 | heading-style = 
 | link box      = 
}}

Inline documentation

{{Documentation
 | heading       = 
 | heading-style = 
 | link box      = 
 | content       = 
<!-- Template documentation content goes here -->
}}

Simulated output for another page

{{Documentation
 | heading       = 
 | heading-style = 
 | link box      = 
 | page          =
}}

Placement and tags

Further information is available at Template documentation § Where to place it on English Wikipedia.

This code should be added at the bottom of the template page after its code, with no space before <noinclude> (as any extra whitespace between the end of the template and the tag will be transcluded along with the intended documentation, unnecessarily consuming vertical page space.):

<!-- The last line of the template code --><noinclude>
{{Documentation}}<!-- Add categories to the /doc subpage instead, please. Thank you. --></noinclude>

Categorization and interwiki links

Depending on where the documentation is saved, proper categorization of and interwiki links to the documented page may be difficult to manage. The Wikipedia:Template documentation § Categories and interwiki links contains a thorough treatment of the potential pitfalls and methods of addressing them.

Testing

You can simulate the output for a given page by using the |page= parameter. For example, if you use the code |page=Template:Listing, the template will behave exactly as if it were on the page Template:Listing, including showing the documentation from Template:Listing/doc, linking to Template:Listing/sandbox, etc. This parameter is useful for testing and is used extensively on the module testcases page.

Technical details

Automatic functions

If the documentation page does not exist, the toolbar links are replaced with a [create] link. It automatically creates the page with preloaded text for a basic documentation page. Preloaded text is similarly used for the /sandbox and /testcases [create] links.

The preload page for the /doc [create] link is Template:Documentation/preload, whereas the preload pages for the /sandbox and /testcases links are Template:Documentation/preload-sandbox and Template:Documentation/preload-testcases, respectively. The preload page for the /sandbox [mirror] link is Template:Documentation/mirror.

When this template is on a /sandbox subpage, it automatically adds the {{Template sandbox notice}} template.

Link box features

Depending on the namespace, the link box may have less features or may not be shown at all. The various behaviors are shown below.

Namespace	Behavior
Template	Full behavior
Module	Full behavior, or displays "Documentation for this module may be created at Module:Module name/doc." if no /doc subpage exists
User	Full behavior
Other namespaces	Hidden, unless |1= is defined (which will show "The above documentation is transcluded from {{{1}}}")

In concert with these modified outputs, if |1= or |content= is defined, the "Add categories to the /doc subpage" will not be shown.

Subject namespaces vs. talk namespaces

This template is usually placed in subject namespaces, but in some cases it may need to be on talk namespaces. When doing so, this template usually is placed near the top of the page and without <noinclude>…</noinclude> tags.

The /doc, /sandbox and /testcases pages should normally be in subject namespaces as well, except in those that do not have the MediaWiki subpage feature enabled, namely: Main, File, and MediaWiki. (Categories can have subpages, but documentation is created in the Category talk namespace to prevent creating empty categories. There are manifold other technical reasons why the /doc page must be stored under the talk page for those (but only those) namespaces, too.

This template automatically targets its [create] links for the /doc, /sandbox and /testcases to the appropriate namespace.

Color scheme

Wikivoyage background colors for {{Documentation}}

	RGB	HSV	Color	General usage	Note
A	#ecfcf4	150°, 6%, 99%		Sample	Current documentation background
B	#00ff80	Hue=150° (41.7%; 106/255dec) 100%, 100%		Basic hue	What we'd call the color
1	#a3bfb1	150°, 15%, 75%		Header border only
2	#cef2e0	150°, 15%, 95%		Main border; header background
3	#e6fff2	150°, 10%, 100%		2nd header, accent color
4	#f5fffa	150°, 4%, 100%		Main background	So saturation in A is a bit off

TemplateData

This is the TemplateData for this template, for use by TemplateWizard, VisualEditor and other tools.

Template description

Provides a uniform presentation for documentation of templates, modules and other tools to inform editors about the functioning and intended uses

Template parameters

Parameter		Description	Type	Status
Documentation page	1	Overrides the standard /doc subpage target and transcludes the content from this page instead Default /doc Example Template:Some other template/doc	Page name	optional
Custom heading	heading	Replaces the default heading the with text supplied, or removes the heading if defined with an empty value Example Climate chart documentation	Line	optional
Heading CSS styles	heading-style	Adds custom styling to the header defaults; values must be valid CSS3 declarations with terminating semicolons (do not enclosing in quotation marks) Default font-size: 1.25em; font-weight: 700; Example color: firebrick; font-size: 1.33em; font-weight: 600; text-decoration: underline firebrick solid 2px;	Line	optional
Custom footer	link box	Overrides the default footer and displays the text provided instead, or suppresses the footer entirely when set to 'off' Suggested values off Default The above documentation is transcluded from Template:Documentation subpage/doc. (edit | history) Editors can experiment in this template's sandbox (create | mirror) and testcases (create) pages. Add categories to the /doc subpage. Subpages of this template. Example The above documentation is stored within this template page; changes to it can be made there.	String	optional
Documented page	page	Simulates output for the page specified instead of the transcluding page; used primarily for testing purposes Default {{FULLPAGENAME}} Example Module:Test	Page name	optional
Documentation text	content	Overrides the transclusion of the contents of a separate documentation page and displays this content instead Example This template is for use on such-and-such a page in such-and-such a setting…	Content	optional

See also

• {{Documentation subpage}} (places a notice at the top of /doc subpages explaining their role and a direct link to the page they're documenting)