Categories are a software feature of MediaWiki, which enables pages to be added to automatic listings. These help structure a project such as Wikipedia by grouping together pages on similar subjects.

Summary

The MediaWiki software maintains tables of categories, to which any editable page can be added. To add a page to a category, include "[[Category:Category name]]" or "[[Category:Category name|Sortkey]]" in that page's wikitext. The categories to which a page belongs appear in a box at the bottom of the page.

A category is usually associated with a category page in the "Category:" namespace. A category page contains text that can be edited, like any other page, but when the page is displayed, the last part of what is displayed is an automatically generated list of all pages in that category, in the form of links. Other category pages which appear in this list are treated separately, as subcategories.

Putting pages in categories

A page belongs to a category if the page's wikitext contains a declaration for that category. A category declaration takes the form [[Category:Category name]] or [[Category:Category name|Sortkey]]. The declaration must be processed, i.e. it will not work if it appears between <nowiki>...</nowiki> or <includeonly>...</includeonly> tags, or in a comment. The declaration may however come from a transcluded page; see Categories in templates below.

A category name can be any string which would be a legitimate page title. It cannot begin with a lower-case letter. If the category name given in a category declaration begins with a lower-case letter, then it is interpreted as if it were capitalized.

In Wikipedia, it is customary to place category declarations at the end of the wikitext, but before any stub templates (which themselves transclude categories) and interlanguage links.

When a page has been added to one or more categories, a categories box appears at the bottom of the page (or possibly elsewhere, if a non-default skin is being used). This box contains a list of the categories the page belongs to, in the order in which the category declarations appear in the processed wikitext. The category names are linked to the corresponding category pages. They appear as redlinks if no category page currently exists.

Hidden categories are not displayed, except as described below under Hiding categories.

To link to a category page without putting the current page in that category, precede the link with a colon: [[:Category:Category name]]. Such a link can be piped like a normal wikilink.

Category pages

A category page is a page in the "Category:" namespace. The page "Category:Name" corresponds to the category called "Name". New category pages can be created like any other pages – by clicking on redlinks or entering the name in the search box and clicking "Go".

A category page can be edited like any other page. However, when it is displayed, the editable part of the page is followed by automatically generated lists of pages belonging to the category, as follows:

• First a count and list of subcategories (other category pages belonging to the category) is shown, if any exist. The name of each subcategory is followed by a count of its own subcategories. These further subcategories are displayed if the "+" sign alongside the subcategory is clicked.
• Next a count and list of pages in the category (excluding subcategories and images) is shown. If the category has no members, a message to that effect is displayed.
• Next a count and list of image and other media files in the category appears, if any exist. These are shown with thumbnails. The first 20 characters of the file name are shown, with an ellipsis if that is not the full name; also the file size is shown.

The items in the lists all link to the pages concerned; in the case of the images this applies both to the image itself and to the text below it (the name of the image).

For the way in which the lists are ordered, see Sort order below. The first and second lists are divided into sections, according to the first character of the sort key. These initial characters are displayed above the sections. To suppress these, make all sort keys start with a space.

A category page can only display a limited number of items (currently 200). If more pages belong to the category, there will be a link to the next ones.

The categories box for the category page appears at the bottom, in the same place as for other pages. This contains the categories to which the current category page has been added, i.e. its parent categories (the categories of which it is a subcategory). Add a category page to other categories in the normal way, using the "[[Category:Category name]]" or "[[Category:Category name|Sortkey]]" syntax.

Hiding categories

When the magic word __HIDDENCAT__ is placed on a category page, that category becomes hidden, meaning that it will not be displayed on the pages belonging to that category. This feature is mostly used to prevent project maintenance categories from showing up to ordinary readers on article pages.

However, hidden categories are displayed (although listed as hidden):

• on category pages;
• at preview during editing;
• if the user has selected "Show hidden categories" in user preferences.

When listed as subcategories on other category pages, hidden categories appear normally.

Hidden categories are automatically added to Category:Hidden categories.

Sort order

The system uses alphabetical order, or more precisely Unicode order, for pages in categories. The range 32–127 corresponds to ASCII (for more see a table of Unicode characters):

  !"#$%&'()*+,-./0123456789:;<=>? @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_ 'abcdefghijklmnopqrstuvwxyz{|}~ 

Note in particular that "Z" comes before "a", and "z" before accented/umlauted characters.

Unlike at Special:Allpages and Special:Prefixindex, a space is treated as a space (coming before all other characters), not as an underscore.

Each of the three lists is arranged in the order explained above (except that in the subcategories list, the namespace indicator "Category:" is not considered). If you want an item in a list to be positioned in that order, based on an alternative name (sort key) for that item, then this can be specified in the category tag that places the item in the list:

 [[Category:Category name|Sortkey]] 

For example to add an article called Albert Einstein to the category "people" and have the article sorted by "Einstein, Albert", you would type "[[Category:People|Einstein, Albert]]".

Although this is like the syntax for a piped link (and in an edit summary it is interpreted like one), there is a clear difference: the second term in the piped link is an alternative term for the first one, while the sort key is an alternative name for the page in which the tag occurs. The name actually displayed is the name of the article, not the sort key. Also, a piped link influences the rendering of the page itself, while a sort key affects the rendering of another page.

It is useful to document the system being used for sort keys on the category page. For guidelines about the use of sort keys on Wikipedia, see WP:SORT.

Default sort key

It is possible to set a default sort key which is different from {{PAGENAME}} by using the magic word {{DEFAULTSORT}} thus:

 {{DEFAULTSORT:new key}} 

In the case of multiple default sort key tags, the last one on a page applies for all categories, regardless of the position of the category tags. This also means that a DEFAULTSORT tag in a template, intended for category tags in that template, for categorization of pages calling the template, is not effective if another DEFAULTSORT tag occurs later on these pages, even if it is also "hidden", in another template.

Use of this magic word is not required on all articles. There is no need to use it if the default sort key is identical to the article name.

Categories and templates

A template can be used to add pages to a category, usually by placing the category link inside <includeonly></includeonly> tags on the template (e.g. <includeonly>[[Category:category name]]</includeonly>). When the template is transcluded into the page, the category link becomes active, and the page is added to the category page. This is useful for categories that have high turnover or many pages included, like cleanup categories.

Changes to the template, however, may not be reflected immediately on the category page. When you edit an article to add a category tag directly, the list of category members is updated immediately when the page is saved. When a category link is contained in a template, however, this does not happen immediately: instead, whenever a template is edited, all the pages that transclude it are put into the job queue to be recached during periods of low server load. This means that, in busy periods, it may take hours or even days before individual pages are recached and they start to appear in the category list. Performing a null edit to a page will allow it to jump the queue and be immediately recached.

To add the template itself to the category page as well, omit the "includeonly" tags. To add the template to a category without categorizing pages on which the template is transcluded, place the category declaration between <noinclude>...</noinclude> tags.

Parser functions can be used to make the transcluded categories, or the sort key used in them, dependent on other variables, notably PAGENAME.

Passing a category by parameter

<includeonly>[[Category:{{{cat|default}}}]]</includeonly> or <includeonly>{{{cat|[[Category:default]]}}}</includeonly>
If the user provides a parameter 'cat=XXX' the page will be categorized at the page [[Category:XXX]], otherwise it will be categorized at the page [[Category:default]]. Calling the template with "cat=" (equal to nothing) disables putting the page in any category.

Excluding non-article pages

<includeonly>{{#if:{{NAMESPACE}} | | [[Category:XXX]]}}</includeonly>
the variable NAMESPACE is null for mainspace articles. For any space other than mainspace, this ParserFunction will produce an empty string, but for regular articles this will include the article in Category:XXX.

Categorizing redirect pages

Redirect pages can be categorized. The category tag has to be put in the first paragraph. In the case that the target of the redirect is a section this has to some extent the effect of categorizing the section: through the redirect the category page links to the section; however, unless an explicit link is put, the section does not link to the category.

On a category page, redirects are listed in italics.

Moving and redirecting category pages

The only way to move a category page is to manually change all category tags that link to the category, and copy the editable part. There is no automatic way to move a category page in the way one moves an article page. For categories entirely populated through templates (see above) modifying the templates allows to move all affected articles to a renamed category, but with the refresh problem mentioned.

Redirecting a category page is possible, but will not cause pages to be recategorized from the redirected category to the target. On Wikipedia soft redirects are preferred for categories, and bots are used to move the pages from redirected categories.

Applying "Related Changes" to a category

For a category the "Related Changes" feature gives the changes in the pages in the category (according to the current category page, so excluding the pages that have potentially been added and including those that have potentially been removed, through addition or deletion of a template to/from the category, as explained above)

• for subcategories: the changes in their editable parts only
• for images (image pages): the changes in their editable parts only.

It does not show the changes in pages linked from the editable parts of the category. Possible workarounds:

• The editable part can be put in a template. The category tags (which have no effect on Related Changes anyway) can better be kept out of the template, because on the pages of these supercategories the template would be listed under the articles in those categories. Whether interwiki links (with or without interlanguage link feature) are in the template or not does not make a difference, provided that the template is not used elsewhere.
• Related Changes is applied to a page that calls the category as a template: {{:Category:Category name}}; only the editable part is included in the page; the page could be specially created for this purpose and call multiple categories. However, this page will then be listed in the supercategory pages of each category.

As usual (but as opposed to a watchlist) the changes in the corresponding talk pages are not shown.

Applying "Related Changes" to a category, with sufficiently high limits on number and days, is also useful for checking which pages in a category one "watches": they are bolded.

If the category contains pages but does not "exist" as editable page, "Related Changes" can be applied, but no link is supplied, one has to supply the URL oneself. It is more convenient to "create" the page first.

For the "What links here" feature, only the links in the editable part of the page count, not the links to the pages in the category.

Detection of additions to a category

With "Related Changes" one can find pages which are newly in a category due to addition of a category tag or the tag of a template that is in the category. Addition of pages through addition to the category of a template is seen indirectly: one can see the change in the template, and then check which pages call the template. This even shows pages which are only potentially in the category (see above).

Unfortunately there is no similar way to detect a deletion from a category.

Comparison with "What links here"

Backlinks are often used as a by-product of links and inclusions. However, links and inclusion tags can be put specially for the backlinks, just like category tags are.

Thus one can create a kind of "category abc" showing its content with Special:Whatlinkshere/abc without an entry in the category lists on each page in the category. With inclusion this can be done in two ways:

• {{#if:|{{:abc}}}} rendering nothing. This works regardless of whether abc exists.
• {{:abc}}. This requires creating a blank page to render nothing, or a page with some content to provide an in-page category listing.

In the case of links

A redirect corresponds to a supercategory.

Advantages of categories

• Category listings are alphabetical, for "What links here" this typically applies for the first part only, for the pages already linking to the given page at the time of the last rebuilding of the link tables in the database.
• Categories have an editable part (however, there is anyway a talk page)
• A category can have multiple supercategories

Advantage of a pseudo-category system using backlinks

• Backlinks can show a tree structure: not only pages and subcategories, but also the contents of the subcategories (for each a list of pages and a list of sub-subcategories) and the contents of the sub-subcategories (for each a list of pages and a list of sub-sub-subcategories), but not the contents of the sub-sub-subcategories, up to three levels are shown.

In the case of inclusions

• also multiple supercategories are possible
• combined content of subcategories is shown in one list, not grouped by subcategory (the tree structure is not shown, but it can be used by taking the backlinks at a lower node, showing the smaller set)
• the restriction of three levels (in the case of using redirects) does not apply; for example page Aijkl in the category Aijk in the category Aij in the category Ai in the category A (represented by Aijkl calling template Aijk, etc.) can be shown in the list of pages in category A (the backlinks of template A).

Category considerations

Check the conventions in a project and make yourself familiar with the categories in use before assigning pages and subcategories to categories and before creating new categories.

It is not obvious whether a page like Amsterdam should be in category City (a description of a member of the category) or Cities (a description of the category as a set of pages). A convention for using one or the other is useful (e.g. on w:en), to avoid ending up with both, with part of the applicable pages in one, and part in the other.

Putting a category tag on a test page, user page, etc. (also if done indirectly by including a template with a category tag) is considered to pollute the category, while regular links from such pages showing up in "what links here" is considered harmless. Therefore:

• when copying text to such pages, category tags have to be removed; alternatively, convert the category to a link by adding a leading colon after the brackets. For example, "[[:Category:Art]]" is a link to the category, not an assignment to a category.
• when including a template that is in a category, do not use the template feature, but use "subst" or copy-and-paste, and delete the category tags.

Extended tools

List of all categories

Special:Categories provides an alphabetic list of all categories, with the number of members of each; this number does not include the content of the subcategories, but it includes the subcategories themselves, i.e., each counting as one. Comparing with Special:AllPages/Category:, note that:

• a category without members is not in the former;
• a category that has not been created as a page is not in the latter (in the former it stands out as red link).

Visualizing category trees

Special:CategoryTree enables you to visualize the tree structure of categories. The CategoryTree extension installed on MediaWiki allows in-page display of the tree. The basic syntax is

• <categorytree>Category name</categorytree>

to display just the subcategory tree, and

• <categorytree mode=pages>Category name</categorytree>

to display member pages as well.

Dapete's category-visualizer Catgraph will render charts of the tree structure.

Dynamic page list

The DynamicPageList (third-party) extension provides a list of last edits to the pages in a category, or optionally, just the list of pages; the simpler DynamicPageList (Wikimedia) is installed on Meta and Wikinews; the extension mw:Extension:DPLforum is installed on Wikia, see http://www.wikia.com/wiki/Help:Forums.

Category intersection, union, etc.

Various MediaWiki extensions allow intersection of categories, union of categories, display of info about the pages in a category, and more:

• Semantic MediaWiki
  • Main Page - start page
  • Introduction - allows further intersection with sets of pages defined in terms of relations and attributes
  • Inline queries - provides relation- and attribute-related info about the selected pages and in-page display on any page of categories the same or another page is in*Forum
  • intersection of categories and complements of categories
  • provides the time of last edit for each page
• Category-/Linkintersection - a toolserver tool to query articles based on boolean expressions of their categories (and, or, not).

They all also allow further restriction to a namespace; some allow also restriction to a union of namespaces, or the complement of a union of namespaces. They all allow the info to be displayed in any page, not just a separate category page.

See also w:Wikipedia:Category intersection.

Category flattening

Category flattening is displaying also the articles in a category's subcategories, sub-subcategories, etc.

• category flattening with Semantic MediaWiki

See also m:Category flatten, and Wikimedia bug 1497.

Count

As described at mw:Help:Magic words, {{PAGESINCATEGORY:Example}} or {{PAGESINCAT:Example}} return the number of articles in Category:Example (including articles in subcategories).

Retrieving category information

Raw information about the members of a category, their sortkeys and timestamps (time when last added to the category) can be obtained from the API, using a query of the form:

• http://en.wikipedia.org/w/api.php?cmtitle=Category:Category_name&action=query&list=categorymembers&cmlimit=500&cmprop=title|sortkey|timestamp