Manual:Skinning Part 1

MediaWiki version:

≥ 1.18

This tutorial details the creation of a custom skin for MediaWiki. The skin is packaged as a directory you can drop into a MediaWiki installation's skins/ directory and enable by calling the wfLoadSkin() function in LocalSettings.php. (Prior to MediaWiki 1.25, you must instead use the require_once.)

• Part 2 of this tutorial deals with the files required to create a skin.
• This page outlines the things you need to take into consideration when creating your skin.
• The actual creation of the HTML, CSS, images, any mockups, or even the idea of what a skin should look like is out of the scope of this tutorial. You'll have to either have the markup, styles, and resources ready, or build up the empty boilerplate and start building the skin from there.

Skin elements

There is more to a MediaWiki skin than it might seem at the first glance. A design of a generally usable skin needs to handle many elements, some that are easily overlooked.

It's easy to create a beautiful design for your site and only later realize that you forgot, e.g. the page actions links to delete or move pages; or created a layout that doesn't fit the edit form, revision differences view and special pages; or didn't reserve a place for any user or site notices. This page describes most of these elements in more detail. On the right there is a picture of some of them.

This doctored screenshot of the Vector skin shows, from top to bottom:

• the personal tools for a logged-in user, including Echo extension's notification badges
• the actions the user can take on the page as a set of tabs (Vector displays namespaces on the left)
• site search
• the (dummy) site notice
• a subpage line and "redirected from" line
• the categories of the page
• the footer with icons and links
• and on the left, part of the sidebar (not shown: toolbox and language links)

You don't need to restrict yourself to the norm: feel free to relocate portions of areas into other spots, like taking the username/talk links out of personal URLs. The important thing is to make sure you don't leave out the things MediaWiki may need to output when you think up the design.

Body area and layout

When mocking up the body area and layout of your skin remember that besides the regular display of an article on the wiki, there are other views of a page and other kinds of pages in MediaWiki:

• users can edit the page, possibly using VisualEditor
• users can view a diff between two versions of a page, a history of the page, etc.
• pages in the File: namespace present images and video
• there are many special pages such as Special:RecentChanges
• extensions can modify pages and add new kinds of pages, such as Flow discussion boards
• users may be able to enable gadgets on the wiki

Many of these can result in very "heavyweight" pages, so much so that you may want to consider giving them a modified wider page in your design if you are doing a fixed-width design. When designing, you can include a mock up of recent changes or an edit page in the body area of your skin.

Subtitles and taglines

When placing the title in your design remember that MediaWiki has some subtitles that usually go below the title. These are usually in the form of a subpage hierarchy, redirected from line, diff/permalink navigation, or delete line. You don't need to use MonoBook and Vector's approach of attached title+subtitles+body, but do keep in mind where such subtitles will go and how they will look.

Site notices and user notifications

MediaWiki has three built-in types of notifications: the site notice, user notice for new talk page messages, and a floating JavaScript message presenting dynamic actions (like adding a page to your watch list). When you mock up your design remember to plan where these notices will go and how will they look.

Search

MediaWiki has a built in search functionality, and the search form is a key part of skins. When designing your skin remember to include a search input in your design, including a style for the search bar that fits in with the rest of the skin. Consider the behavior of built-in search suggestions.

Personal tools

MediaWiki includes a bar with a number of personal tools (links to log in/log out, user and talk page, watch list, preferences; more can be added by extensions). You can implement custom behaviors for particular items, but remember that other links can be added to this bar and you should have some location for the rest of the functionality you didn't add custom stuff for in your skin.

Actions

MediaWiki includes a number of page-specific actions: anyone can read, edit, and view history, and logged-in users can add to watchlist, move, etc.. Many skins display these as tabs or menu items. You have two formats you can work with this in, a single flat list (see MonoBook for reference) and a set of lists categorized into namespaces, variants, views, and actions (see how Vector separates them into separate areas and menus). Whether you use a flat list, grouped lists, or even pull some of them out and make buttons be sure you have a place for these: they are an important part of MediaWiki and easy to forget about if you are used to skinning other content platforms like WordPress.

Navigation

MediaWiki includes a built-in sidebar for site navigation that its Skin class generates from the the on-wiki configuration "message" MediaWiki:Sidebar. You can adapt this with CSS to whatever type of navigation you want in a design, and you can create additional or replacement site-defined navigation specific to your skin.

Toolbox

MediaWiki skins usually also include the functionality that MonoBook and Vector group into a toolbox. These tools include generic links such as a special pages link and page-specific links such as permanent link, What links here, and printable links. Like the personal tools you can move pieces of these wherever you want, but since more links can be added to these tools be sure to have a place for the rest of the links you have not moved.

Language links

MediaWiki supports inter-language links from one page to the same page in a wiki of another language. One of the skin's responsibilities is to define a place for this list of language lines to go. Be sure to consider a place for it, even if you just throw it in a sidebar as MonoBook and Vector do.

Page status indicators

MediaWiki version:

≥ 1.25

Pages can have page status indicators, icons and/or short text snippets providing information. For example, the help link on Special:Contributions and other specialpages.

Footer icons and footer links (optional)

Skins typically include a series of links and icons. These include things like the license / copyright of the wiki, a "powered by" icon, links to about, disclaimer, and privacy policy. When designing your skin consider if you want these or have a reason to leave them out of your design. When including them also consider how you are going to style them.

Other elements

Vector shows these elements at the bottom:

• Content pages can be in one or more categories, and skins show these as links somewhere.
• Extensions can add content to a page in a SkinAfterContent hook, which skins normally display after the content.
• There is some technical HTML that must be output at the end of a page. class BaseTemplate (explained in Part 2) has a printTrail() method that handles these, if your skin doesn't use it then you need to output:
  • a debugging toolbar that may be enabled during development
  • "bottom" scripts that can run after the HTML of the page
  • performance timing information.

Further reading

• Read Manual:Skinning Part 2 for the code to make your skin display something to the user.
• Read Manual:Skinning Part 3 for additional things you need to consider and test for your skin.