Template:Documentation/doc: Difference between revisions
(Creating documentation subpage for the documentation template. Documentationception?) |
(Removing TOC from the main page documentation) |
||
| Line 18: | Line 18: | ||
Writing a documentation subpage is pretty much like writing a normal article - you just explain what the template does - an article on the template, if you will. You can even edit the templatedata in the documentation subpage, and have it be used by the template itself! The editor even supports that. You can see an example of that in the documentation subpage for this template. | Writing a documentation subpage is pretty much like writing a normal article - you just explain what the template does - an article on the template, if you will. You can even edit the templatedata in the documentation subpage, and have it be used by the template itself! The editor even supports that. You can see an example of that in the documentation subpage for this template. | ||
That said, there's one caveat when it comes to /doc subpages - categorizing. You may not want to have your template share categories with its /doc subpage. To go around that you simply use <nowiki><noinclude></nowiki> tags for what the documentation subpage should have, and <nowiki><includeonly></nowiki> tags for the template's categories. You can see an example at the end of this template's /doc subpage. | That said, there's one major caveat when it comes to /doc subpages - categorizing. You may not want to have your template share categories with its /doc subpage. To go around that you simply use <nowiki><noinclude></nowiki> tags for what the documentation subpage should have, and <nowiki><includeonly></nowiki> tags for the template's categories. You can see an example at the end of this template's /doc subpage. | ||
==Template Data== | ==Template Data== | ||
| Line 52: | Line 52: | ||
</templatedata> | </templatedata> | ||
<includeonly>[[Category:Templates]]</includeonly> | <includeonly>[[Category:Templates]]__NOTOC__</includeonly> | ||
<noinclude>[[Category:Documentation subpages]]</noinclude> | <noinclude>[[Category:Documentation subpages]]</noinclude> | ||
Revision as of 21:48, 21 June 2023
This template displays documentation for the template page it's placed in in a neat format (The format is still a work in progress - hit me up here or on Discord if you feel like brainstorming it!).
Usage
Only use this template between <noinclude> tags, or it will put the entire documentation in any page that uses the template, or create redlinks. All in all, don't try it.
Use the CONTENT parameter (aliased as 'Content' and 'content' for ease of use) to simply display whatever its value (which can be any wikitext) in the documentation format.
Omitting the CONTENT parameter transcludes the /doc subpage of the current page. You're seeing the results of this right now. Doing this also displays a line of links to view the documentation page, edit it and view its edit history.
Use the HEADING parameter (similarly aliased as 'Heading' and 'heading') to change the default documentation title to a different short text.
Why the separation?
There are two main reasons for why one may want a separate documentation subpage for a template:
- It reduces clutter - if you see an edit on the template page, then you know it's changing the template's functionality. If you see an edit on the /doc subpage, it's changing the documentation - it makes it easier to track what one may be more interested in.
- If there's an important, widely-used template, it may be a good idea to protect it. The separation of template and documentation means that even if a template is protected from edits, its documentation can still be edited - saving the time for power users to have to do spell checking and the likes.
Writing a /doc subpage
Writing a documentation subpage is pretty much like writing a normal article - you just explain what the template does - an article on the template, if you will. You can even edit the templatedata in the documentation subpage, and have it be used by the template itself! The editor even supports that. You can see an example of that in the documentation subpage for this template.
That said, there's one major caveat when it comes to /doc subpages - categorizing. You may not want to have your template share categories with its /doc subpage. To go around that you simply use <noinclude> tags for what the documentation subpage should have, and <includeonly> tags for the template's categories. You can see an example at the end of this template's /doc subpage.
Template Data
Displays documentation for the template this is currently placed in. This includes categories.
| Parameter | Description | Type | Status | |
|---|---|---|---|---|
| Heading | HEADING Heading heading | Replaces the default text at the header of the documentation with a different text
| Line | optional |
| Content | CONTENT Content content | If not specified or is blank, transcludes the /doc subpage of the page the template is currently placed in. Displays whatever wikitext is provided to this parameter otherwise. | Content | optional |