Français
Italiano | This template uses Lua: |
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
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
| 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
| Parameter | Description | Type | Status | |
|---|---|---|---|---|
| Documentation page | 1 | Overrides the standard /doc subpage target and transcludes the content from this page instead
| Page name | optional |
| Custom heading | heading | Replaces the default heading the with text supplied, or removes the heading if defined with an empty value
| 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)
| 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'
| String | optional |
| Documented page | page | Simulates output for the page specified instead of the transcluding page; used primarily for testing purposes
| Page name | optional |
| Documentation text | content | Overrides the transclusion of the contents of a separate documentation page and displays this content instead
| 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)
Explore the world
United states
New York
Japan
Tokyo
Singapore
Singapore
