Manual:How to make a MediaWiki skin

Making a skin is a great way to get familiar with the inner workings of MediaWiki and to kick off your contributions to the Wikimedia movement! If you are familiar with the front end technologies of CSS, JavaScript and JSON you can make a MediaWiki skin! There is no need to know PHP, but it may help if you want to do anything advanced.

While not essential, it will help if you are familiar with [ http://lesscss.org/ LESS CSS]. This tutorial assumes that you have installed a working version of MediaWiki, and are running the current development release, if not, it is recommended you do that first.

If you having an existing skin using the PHP BaseTemplate, this guide is not for you. Please see Manual:How to make a MediaWiki skin/Migrating SkinTemplate based skins to SkinMustache instead.

Preparation
Skin development will be a lot easier with a familiarity with [ https://mustache.github.io Mustache templates].

At minimum, you should be familiar with the following Mustache basics described in the example below:

A skin is responsible for the rendering of user-visible content - the HTML inside the BODY tag. It is restricted from editing anything inside the HEAD. Code will be automatically generated for the skin, so that the skin can focus on presentation. If you need to modify the HEAD this is considered outside the scope of the skin, please use Hooks, extensions or configuration to do that see the FAQ for best practices on how to do that.

Getting started
To begin making your first skin, we recommend two options.

Option 1 - Fork Example skin
The Example skin https://github.com/wikimedia/mediawiki-skins-Example provides the bare bones implementation of a skin. Clone the repository in your skins folder making sure the folder is called " Example " and add the following to your LocalSettings.php :

If all has gone to plan your skin should be available on the Special:Preferences page of your wiki.

Option 2 - Use the skins lab
The [ https://skins.wmflabs.org/#/add skins lab tool] allows you to setup a skin with basic CSS and templates. Once you feel comfortable, you can click "download as ZIP" which will compile the necessary boiler plate for your skin. Hopefully the resulting repository is easy to navigate. When you have downloaded the ZIP place it in your MediaWiki skins folder and update LocalSettings.php with the following:

If all has gone to plan your skin should be available on the Special:Preferences page of your wiki.

Option 3 - From the command line
When you have downloaded the ZIP place it in your MediaWiki skins folder and update LocalSettings.php with the following:

Let people know!
Making a skin will be more fun with other people and much easier too! Once you have got something usable, please consider publishing it to GitHub or. Once the code is publicly available, you should [ create a skin page] (make sure you change the title!) to let people know you are open for collaboration!

Setting up a wiki page has many other benefits. You'll be able to handle bug reports in Phabricator  or GitHub issues and receive patches from other volunteers in the MediaWiki community. Somebody should also be able to help you setup translation.

Mustache
In 1.35 we added support for Mustache in skins. We found using Mustache to be very helpful in the development of the Skin:Minerva and Skin:Vector skins as it allows you to separate data from presentation. Mustache partials can be used to reuse templates. To use a partial Partial.mustache in MediaWiki, simply add them to the folder you are working in and reference them using in the master template ' skin.mustache '.

The data sent to Mustache templates is relatively flexible. If something is missing, you can use PHP to add data by extending the ::getTemplateData function.

The [ https://github.com/jdlrobson/mediawiki-skins-skinjson SkinJson] skin can be added to a MediaWiki development instance, to inspect the data available to skins. Note that arrays are prefixed " array- ", booleans are prefixed with " is- " and objects are prefixed " data- " to help you conceptualize the data you are working with.

The data available, and in which MediaWiki versions it is available is documented on SkinMustache.php.

Making your skin translateable (i18n)
In skin.json under ValidSkinNames, you can use the `messages` option to define translatable message keys. These keys should correspond to entries inside the i18n/en.json folder. Once registered for the skin, these will be available in your template with a prefix.

For example in the example below, the message " sitetitle " can be rendered in a Mustache template using:

See Localisation for more information on why this is important.

Rendering template partials
Template partials can be used to render different parts of the skin and to avoid the problem with having a large unmaintainable skin.mustache file. In the following example, the skin renders the contents of the templates in the 3 files with the filenames Logo.mustache, Content.mustache and Footer.mustache. These files must exist in the same folder as the  skin.mustache  file or a subfolder of the directory containing skin.mustache.

Template partials are a great way to break up your skin to make it more readable. No template partials are predefined and available by default, however you can [ https://codesearch.wmcloud.org/skins/?q=%7B&i=nope&files=.*.mustache&excludeFiles=&repos= look at existing skins using SkinMustache for inspiration].

Read more about [ https://mustache.github.io/mustache.5.html#Partials Mustache template partials].

Logo.mustache
Following code block is being used to show the site logo in the Example skin and you will also see the same if you create the skin from the SkinLabs.

From the code block mentioned above, the following line is responsible to show the logo ` icon `:

This line assumes that, there is a key in the array. So in your LocalSettings.php file, if there is a line similar as, then the logo/icon image will be displayed. The default MediaWiki exports a  key in the  array.

So to show the logo you need to update the LocalSettings.php and add a key.

Rendering menus with Mustache
All menus are structured in the same format (PortletData). A generic  Menu.mustache  template partial, added to the same folder as  skin.mustache  can therefore be used to generate a menu. However, when using this partial you'll need to tell it which menu to generate HTML for.

Inside skin.mustache the following would render the languages and views menu.

Rendering dropdown or sub-menus
Skin designers can also use the mustache syntax to create dropdown menus from the elements previously found in the sidebar of the Vector and MonoBook skins. This is a little trickier, however, but understanding the way the elements are stored can help.

The first sidebar element — typically containing the main page link and other MediaWiki links, is rendered via the call. Subsequent menus, however, are stored in the array, and can be rendered by calling this.

For example, one may use the following syntax: Which, when CSS is applied to hide " dropdown-content " until " mw-dropdown-title " is hovered over, thus creating a dropdown menu.

Disabling the table of contents
In MW 1.38, you can remove the table of contents from the article body and position it outside the content area. To disable the table of contents generation, add the following to skin.json :

The  array-sections  template key can be used for rendering the table of contents.

More examples
To see examples of template partials that can be used in your project, you can look through the examples in [ https://github.com/jdlrobson/skins.wmflabs.org/tree/main/src/starter-template the Wikimedia skins labs].

Defaults
A skin at minimum requires a single style ResourceLoader module defined in your skin's  skin.json  file. It will look a bit like this:

The features key allows you to use useful boiler plate defaults for a variety of things including i18n and normalize which are documented in the [ https://doc.wikimedia.org/mediawiki-core/master/php/classMediaWiki_1_1ResourceLoader_1_1SkinModule.html#details MediaWiki core php documentation]. Features can be an array of keys (opt-in policy) or in MW 1.36 an associative array (opt-out policy, recommended). If you are not sure, please omit the features key to use the recommended defaults.

CSS / LESS
The skin.json is a manifest of all the assets your skin uses. Under the ` ResourceModules ` key you should find the style module for your skin listed under ` skins.example `. Here, under the " styles " key you can add LESS or CSS files. They will be loaded in the order they are listed. With LESS you can use statements in the same folder. More information about what's possible can be found in Developing_with_ResourceLoader.

When using images you should be able to use relative URIs to access the image assets.

MediaWiki Skin Variables
MediaWiki skin variables have been around since MW 1.35, recent development enabled them to work for broader use.


 * For skin designers: Skin variables offer a way to quickly implement design choices by setting values in a flat list. This straightforward list is grouped by CSS properties. It must be located in folder and file 'resources/mediawiki.less/mediawiki.skin.variables.less' in order to be picked up by ResourceLoader. The naming scheme follows the MediaWiki variables naming convention.
 * Defaults: If a skin doesn't specify certain values, the system will automatically use the defaults from MediaWiki's own 'mediawiki.skin.defaults.less'.
 * Customization: While you can't modify the variable names, you could define additional ones in separate skin specific files. In every Less file, you can import the skin's values by only
 * Centralization Benefits: All the variables definition for the Wikimedia default theme and all the naming is centralized in order to
 * Establish a consistent naming convention for clarity and uniformity
 * Ensure compatibility across various skins and extensions
 * Provide insights into potential gaps or areas of improvement based on common usage patterns

Skin authors are encouraged to familiarize themselves with these updates to maximize the potential of their skins.

Over 35 different skins and extensions use the skin variables in MW 1.41 already.

Responsive skins / adding a meta viewport
If you are building a responsive skin, make sure to use the  responsive  skin option when declaring your skin in  skin.json .

Making skins compatible with languages that are right-to-left (RTL)
The scripts of certain languages e.g. Hebrew are in right to left rather than left to right. This presents a problem for skin developers, where interfaces are flipped e.g. in Vector the sidebar is on the left rather than the right.

In MediaWiki it's also possible to use a different language for the skin and the content. For example, in Special:Preferences you can set your language to Hebrew while retaining the content in English.

Writing skins that work well in RTL is a large topic out of scope for this document, but if you need to test your skin in RTL you should update LocalSettings.php to change your content language:

As a skin developer you should keep in mind two things:


 * Any CSS written for your skin will be flipped automatically via the CSSJanus tool without any work required from you, however you may need to disable some of those transformations (see Flipping).
 * Any HTML you render that can be translated should be marked up with the [ https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir dir HTML attribute]]. For your convenience SkinMustache provides the html-user-language-attributes template variable which can be used like so:

for a user who has set their language to Hebrew in preferences, produces the following HTML:

Images
You can extend with any data you choose to. This will allow site admins to configure images as they choose, but you must always conditionally render them.

In cases where images must be hardcoded for some reason, and cannot use a CSS background-image or wgLogos, you will need to extend the data sent to the template

JavaScript
JavaScript code in skins, runs in an environment where you can rely on the ` mw ` and ` jQuery ` objects having been loaded. We recommend using ResourceLoader/Package_files which will allow you to require file assets.

For information on the available API and libraries see [ https://doc.wikimedia.org/mediawiki-core/master/js/ core JS documentation].

More advanced
More advanced information will provided on an as requested basis. Please ask a question on the talk page to accelerate the addition of documentation!

i18n
Messages defined in i18n/en.json can be passed directly to your Mustache template by inclusion in skin.json. Note, that you can use [ https://github.com/wikimedia/mediawiki/blob/master/languages/i18n/en.json any messages defined inside MediaWiki core].

Extending data
The data available is documented on SkinMustache.php.

If you need to add additional data for rendering inside your skin's template that cannot be served by messages (as in the i18n section) e.g. raw HTML or complex data structures you must use a dedicated PHP class and extend the SkinMustache::getTemplateData method.

Default styling via the ResourceLoaderSkinModule class
All skins should define a single style module with the class ResourceLoaderSkinModule. The module defines various default styles to take care of MediaWiki internals. If you want, you can disable these features and provide your own styles. Define features as an empty object to tie yourself into the recommended MediaWiki defaults. A [ https://doc.wikimedia.org/mediawiki-core/master/php/classResourceLoaderSkinModule.html#a116386732cae5f8e58f72229f0dd7242 list of support features] is provided in our docs.

Example ResourceLoaderSkinModule that disables the logo feature but enables several others:

Integrating with other extensions
Extensions should integrate with you, not the other way round! Try to forget about extensions when writing your skin. Skins for extension developers is provided for extension developers to ensure they get the best compatibility. The starter templates in Getting_started will render all possible UI elements. If you omit certain pieces of data you may break support with extensions.

For certain extensions you may want to tweak the styles of the default UI elements, notably Extension:Echo. To do this you will need to read.

Changing menu content
The composition of menus can be changed by using hooks. For example [ https://github.com/wikimedia/Vector/blob/master/includes/Hooks.php#L137 in Vector], the SkinTemplateNavigation hook is used to relocate the watch star icon. When doing this, remember to check the skin being operated on, to avoid side effects in other skins.

I want to change elements in the head of the HTML page
Skin developers should not concern themselves with modifying anything in the HEAD of a document. Modifications of the HEAD are better served via extensions and configuration inside LocalSettings.php.

The following links may be helpful:



I am writing an extension that needs to style itself differently depending on the skin
Extensions can make use of skin styles to ship skin-specific styles using the skinStyles key. See.

Building skins for 1.35
In 1.35 support for building skins was not as straightforward as in 1.36. If you wish to build a skin for 1.35, using template data provided in 1.36, you will need to extend the SkinMustache  PHP class. A polyfill for the Example skin is provided.

Your feedback is important
If something is not easy, we'd like to make it easier, so your feedback is important. If you run into problems, then please file a bug report in the mediawiki core skin architecture project in Phabricator, and we'll try and find an elegant solution.

Please feel free to ask a question on the talk page. There is no such thing as a stupid question.