MediaWiki

Placing template styles and documentation on its own namespace

To have templates more manageable and maintainable, Wikipedia has documentation of templates on a separate page. They're in the /doc subpage of the template. In a similar way, with the introduction of Extension:TemplateStyles to move styles outside of the template logic/markup, styles are put also on a subpage of the template, called /styles.css.

However, there may be another approach: Instead of putting them inside a subpage, they could be put on a specific namespace. Because, well, those subpages are not templates.

This discussion may get moot when Multi-Content Revisions can be used to host documentation and/or template styles (task T200687) inside the same template but on different slots.

Implementation

edit

Define the namespaces in LocalSettings.php (they can be named however you like): 

$wgExtraNamespaces[120] = "Template_documentation";
$wgExtraNamespaces[121] = "Template_documentation_talk";
$wgExtraNamespaces[122] = "Template_styles";
$wgExtraNamespaces[123] = "Template_styles_talk";

# Mark the entire namespace as using the Template Styles content model
$wgNamespaceContentModels[122] = 'sanitized-css';
$wgTemplateStylesNamespaces = [ 122 => true ];
# Allow TemplateSandbox to display on pages in the Template styles namespace
$wgTemplateSandboxEditNamespaces[] = 122;

You may also want to tune $wgNamespaceRobotPolicies to use the same policy as the Template: namespace.

If you have Extension:TemplateData, it doesn't support other namespaces. You'll have to add this snippet to MediaWiki:Common.js: 

$(function(){
  // Load the TemplateData editor in the Template_documentation namespace
  if ( mw.config.get('wgCanonicalNamespace') == 'Template_documentation' &&
      mw.loader.getState('ext.templateDataGenerator.editTemplatePage') == 'registered' )
  {
    if ( $( '.tdg-editscreen-placeholder' ).length === 0 ) {
      $( '<div class="tdg-editscreen-placeholder">' ).prependTo( '#mw-content-text' );
    }
    mw.loader.load('ext.templateDataGenerator.editTemplatePage');
  }
});

Comparison

edit

Let's see a list of benefits/disadvantages of each approach.

Issue Subpages Namespaces
List all related pages from a template   Support   Oppose
Special:PrefixIndex works well to list all related pages of a template... only when they're subpages. There's no similar special page to list the same page under different namespaces.

On the other hand, Extension:Scribunto already puts modules on its own namespace. And sometimes TemplateStyles would be in a subpage of the module namespace too (task T200914).

Automatic breadcrumbs   Support   Oppose
Subpages get automatic breadcrumbs to point to the template. This is not true when they're on different namespaces, which makes more difficult to get to the related template from the documentation page or the template styles page.

Extension:Scribunto also expects module documentation to be a subpage of the module, displaying it directly on the module when present.

Renaming templates   Support   Oppose
When renaming a template, all subpages can be renamed at the same time, too. This is not the case when the pages are on different namespaces. Talk pages associated to a subject page are an exception, though, and maybe there's a way to treat them the same way.

While the documentation page is usually included with a template that automatically looks for the subpage, the reference to template styles will usually specify the full page name. This means the template should be edited after the move to point it to the new name. This can be deferred, though, if you don't delete the redirect when renaming the template.

Prevent namespace proliferation   Support   Oppose
Namespace proliferation can pollute namespace filters in Recent Changes, Special:Contributions, etc., since each namespace adds another for their associated talk page.
List only templates/documentation/styles   Oppose   Support
When looking only for templates, the presence of such subpages introduces noise when using Special:AllPages or Special:PrefixIndex.

Categorizing all templates would help when using those categories to look for templates, instead of the special pages.

Autocompletion   Oppose   Support
Template autocompletion (for example, provided by Extension:LinkSuggest) will not be polluted by those subpages.
Special:UncategorizedTemplates pollution (task T305363)   Oppose   Support
Uncategorized subpages will be added to the Special:UncategorizedTemplates page. This is often the case for documentation templates and template styles subpages. The workaround is to categorize those subpages too.
More granularity when protecting the template namespace   Oppose   Support
Templates can be used on thousands of pages. Edits in the template namespace can be restricted without affecting the template documentation, if the template documentation is on a different namespace.
Retrieved from "https://www.mediawiki.org/w/index.php?title=Placing_template_styles_and_documentation_on_its_own_namespace&oldid=5947917"