Page MenuHomePhabricator

RFC: A modern and restrictive (but flexible!) skin system using Mustache
Closed, ResolvedPublic


NOTE: This RFC is a draft but please feel free to contribute thoughts to help me articulate my own! Please also let me know if I can clarify anything! NOTE: Although I'm associated with WMF this is likely to be a personal project if accepted done during volunteer time.
  • Affected components: Skin, TemplateParser, Selected(and stable) skins: Modern/CologneBlue/Monobook, potentially API
  • Engineer(s) or team for initial implementation: (Ideally) Core Platform + Web
  • Code steward: TBD


There is dissatisfaction with the existing skin system. I recently documented this in a blog post Why does building a skin require PHP knowledge?

As far as I can see the main issues being:

  • It’s difficult to create a new skin unless you have a wide range of skills including knowledge of PHP and backend technologies as well as mediawiki internals
  • Deploying an existing skin into production adds a huge maintenance burden given the lack of boundaries to the skin system
  • It is difficult to integrate extensions with existing skins which do not share a common markup or API for key interface elements.
  • We have a few 'official' and modern looking skins released in the tarballs and very few skin developers
  • Most mediawiki instances are using the Vector skin and sharing look and feel with other sites because of the above reasons

Who am I?

I have 8 years of experience of writing skins for MediaWiki full time. I built the Minerva skin and am now working on the desktop refresh. I’ve hit many of the issues with the existing skin “architecture” and exploited the lack of boundaries in the development of Minerva.

Having grown up in the Myspace and Tumblr generation, I’ve seen first hand at what is possible when you lower the barrier for entry for would-be developers. My theory is that by removing the need to know PHP we will open ourselves up to a larger audience of skin developers.

TODO: Add data around skillset availability for PHP+CSS+JS vs CSS+JS.



1. a skin can be built without php

  • It should be possible for a skin to be declared as being a modern Mustache skin without extending a PHP class
  • It should be possible to create a skin using only the JSON, CSS (or LESS), Mustache (HTML) technologies.
  • A skin can optionally use JS and PHP if necessary.

2. A stable skin API

  • Flexible template data that is subject to a strict and stable skin API is sent to the Mustache template. This template data will use a PHP unit test to enforce the following rules:
    • Any HTML will be prefixed with html-
    • Any data will be prefixed with data- (associative array) or array- (if flat array)
    • The template data will be subject to the deprecation policy.
    • Mustache/TemplateParser will emit warnings if template keys that don't exist are used (see T128864)
    • Template keys that are deprecated will emit deprecation warnings using the solution for T128864
    • The data can be modified by the appropriate constrained hooks

3. autodiscovery of assets

  • A skin declared as a Mustache skin will automatically have a stylesheet associated with it that is provided by the ResourceLoader module `skins.<skinkey>". If none is defined then the skin will appear unstyled.
  • A Mustache skin will automatically add a ResourceLoader module `skins.<skinkey>.scripts" as its JavaScript entry point. If none is defined the skin will be assumed to have no JavaScript code
  • A skin declared as a Mustache skin must declare a template at the path templates/skin.mustache folder.
    • If no template is found a RuntimeException will occur.
    • A skin may use template partials if wanted. They can use arbitrary names.

4. restrictions and constraints

  • Skins using the Mustache render will no longer be able to declare their own hooks other than those provided by core. This will keep the skin API scoped. Extensions wanting to target skins are free to check skin name inside hooks.


Skins are encouraged to use i18n. Skins will be able to use template keys prefixed with msg- which will be automatically provided during template rendering.


  • Reduce the amount of hooks that a skin needs to integrate with. The hooks will deal with data rather than output and will be strengthened to meet existing extension requirements.
  • We will implement a Mustache based skin architecture that matches the specification
  • The new skin API is documented and stable.
  • We will rewrite Modern, Cologne Blue and Monobook in the new system to simplify their code using the new skin API.
  • The ExampleSkin is deprecated and updated to point to a skin generator based on which will generate frontend only scaffolding for a skin with updated best practices.
  • We will create a healthier skin ecosystem.
  • We will have a more maintainable skin ecosystem.


Once a specification is agreed upon, I hope to make use of Core Platform Team Clinic Duty

Proof of concept:

The following two patches should hopefully capture the vision here

The fully functional Skinomatic tool should hopefully showcase the power of utilizing the underlying technologies (be sure to click build button in top right and try the resulting zip file in your MediaWiki instance!


what about Vue.js?

Mustache is currently in core so this is why I am using it. My main focus is abstraction. In future it should be very straight forward for a skin to define a Vue based template using skinname.vue rather than skinname.mustache. I will be keeping tabs on the work there particularly around server side rendering to make sure the new skin system is agnostic to templating language.

Further Inspiration


Event Timeline

Can this idea be extended to provide multiple end-user-selectable colour themes for a given skin? E.g. light, sepia, dark, black as in the mobile Wikipedia app and various eBook readers. Ideally something that can be toggled anywhere without going to Settings/Preferences.

I've read about difficulties maintaining the Themes extension when platform changes occur like with ResourceLoader. Bringing support for colour themes into core would benefit all MediaWiki installations, but note that dark mode has been a highly-requested feature for Wikipedia in particular.

Or is stylesheet selection a completely separate thing?

In future yes and this should make that easier. It would be possible in the long term future to create a theme with a simple LESS definition of variables. T123359 will provide most of the groundwork for that. From a skin designers POV they'll be able to create a LESS file with a specific name e.g. theme.less to invoke it.

daniel subscribed.

Moving this to the "resourcing" phase. Is there any commitment to implementing this?

Not officially from my WMF team, but I am committed to implementing this in my 10% time and as a byproduct of the desktop refresh project where interests overlap if I can find fellow reviewers/supporters.

xSavitar updated the task description. (Show Details)
xSavitar updated the task description. (Show Details)

@Jdlrobson, how will GlobalPreferences fit in this picture? Is this new approach of building skin be compatible with GlobalPreferences too? As it has something to do with the current approach of how skins can be set globally by users?

Or maybe this is completely unrelated to the GP extension?

Existing skins will continue to be supported so everything about skins should work as it currently does. The only proposed change would be skins can be simplified under the hood.
From a developer POV you'll be able to write a skin without a single line of PHP using the line

"ValidSkinNames": {
		"modern": "Mustache"

where Mustache refers to the core SkinMustache class

Jdlrobson renamed this task from RFC: A modern and restrictive skin system using Mustache to RFC: A modern and restrictive (but flexible!) skin system using Mustache.May 27 2020, 10:14 PM

Change 584088 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/skins/MonoBook@master] WIP: Monobook Mustache

One point is not immediately clear for me: Does this proposal aim to remove the option of writing PHP-based skins altogether, or does it preserve the option of using PHP to implement a skin if need be?

@TK-999 it preserves the option of using PHP. For some things that still makes sense, but the theory is that Mustache-only skins should be easier to build and maintain as they are logic-less renderings of well defined data.

Jdlrobson claimed this task.

All goals have been achieved so doesn't seem like any reason to keep this RFC open. Thanks to the people who've participated through contributing code, ideas, and code reviewing. If you have any questions/concerns about the new system feel free to raise them on the talk page @

The new skin API is documented and stable.

The only thing I didn't cover is:

We will rewrite Monobook in the new system to simplify their code using the new skin API.

This has been pulled out into T285989