How to Create a Custom CSS Theme in MediaWiki

MediaWiki separates the skin (the PHP/HTML structure) from the theme (a bundle of CSS that decorates a skin). If you want a unique look for your wiki without touching core files, the recommended path is to create a custom CSS theme that works with an existing skin such as Vector or Timeless. This guide walks you through the whole process – from preparing the theme files to activating them on your wiki.

1. Understand the Building Blocks

• Skin – PHP code that renders HTML. MediaWiki ships with a few skins (Vector, Timeless, MonoBook, etc.). Skins are stored in skins/ and are selected via $wgDefaultSkin in LocalSettings.php.
• Theme – a set of CSS files that are layered on top of a skin. Themes are defined by the Extension:Theme and are stored in the extensions/Theme/themes/ directory.
• Site‑wide CSS – the traditional way to tweak appearance is editing MediaWiki:Common.css. This works but mixes custom styling with core CSS and makes upgrades harder. A dedicated theme keeps your changes isolated.

All three mechanisms are described in Manual:CSS and Manual:Themes.

2. Install the Theme Extension (if not already present)

The Theme extension is not bundled with MediaWiki core. Install it via Composer or by cloning the repository:

composer require mediawiki/theme

or

git clone https://gerrit.wikimedia.org/r/extensions/Theme.git extensions/Theme

Then add the extension to LocalSettings.php:

wfLoadExtension( 'Theme' );

After a quick php maintenance/update.php the extension is ready.

3. Create Your Theme Directory

Inside extensions/Theme/themes/ create a folder named after your theme, e.g. mycustom. The structure should look like this:

mycustom/
├─ theme.json
├─ common.css
├─ vector.css   # optional, skin‑specific overrides
└─ README.md

theme.json tells MediaWiki about the theme:

{
  "name": "MyCustom",
  "description": "A lightweight dark theme for Vector",
  "author": "Your Name",
  "url": "https://example.com",
  "license": "MIT",
  "styles": {
    "common": "common.css",
    "vector": "vector.css"
  }
}

The common.css file contains rules that apply to all skins; vector.css holds overrides that only affect the Vector skin.

4. Write the CSS

Start with a minimal reset that respects MediaWiki’s built‑in classes. A safe pattern is to prefix all selectors with .mw-body (the main content wrapper) to avoid accidental clashes with third‑party extensions.

/* common.css – basic colour palette */
.mw-body {
    background-color: #1e1e1e;
    color: #e0e0e0;
}

/* links */
.mw-body a {
    color: #71bfff;
}

/* headings */
.mw-body h1, .mw-body h2, .mw-body h3 {
    color: #ffcb6b;
}

For a Vector‑specific tweak, for example changing the top bar colour:

/* vector.css – top bar */
.vector-header {
    background: #282c34;
    border-bottom: 1px solid #444;
}

Remember to test your CSS with the browser’s inspector (right‑click → Inspect) and to clear caches (?action=purge or hard‑refresh) after each change.

5. Register the Theme with MediaWiki

After creating the files, tell MediaWiki which skin(s) the theme should apply to. Add the following to LocalSettings.php:

$wgDefaultTheme = 'mycustom'; // optional – makes it the default for all users
$wgThemeSkins['mycustom'] = [ 'vector', 'timeless' ]; // skins that can use the theme

If you want users to be able to switch themes via their preferences, enable the UI:

$wgDefaultUserOptions['theme'] = 'mycustom';
$wgHiddenPrefs = array_diff( $wgHiddenPrefs, [ 'theme' ] );

When the page is reloaded, MediaWiki will load common.css for every skin and the skin‑specific CSS for the selected skin.

6. Optional: Per‑User Overrides

MediaWiki still supports the legacy Special:MyPage/common.css (or Special:MyPage/vector.css) pages for personal tweaks. If you enable $wgAllowUserCss, individual users can add CSS that is loaded after the theme files, allowing personal branding without touching the global theme.

$wgAllowUserCss = true;

These per‑user styles are useful for testing changes before promoting them to the shared theme.

7. Debugging Tips

• Cache – MediaWiki caches CSS aggressively. Append ?action=purge to a page URL or run php maintenance/purgeCache.php on the server.
• Specificity – If a rule does not apply, increase its specificity or use !important sparingly.
• Restricted pages – By default custom CSS does not affect login or preferences pages. Set $wgAllowSiteCSSOnRestrictedPages = true; if you need a unified look.
• URL resources – MediaWiki blocks external url() calls for privacy. Host images or fonts on Wikimedia Commons or on the same domain.

8. Upgrading and Maintenance

Because the theme lives in its own directory, MediaWiki upgrades do not overwrite it. When a new MediaWiki version introduces new core CSS classes, you may need to add corresponding selectors to keep the theme consistent. A good practice is to keep a README.md that lists the MediaWiki version the theme was built against and any known incompatibilities.

9. Full Example – Putting It All Together

Below is a minimal, functional theme called mydark that works with Vector and Timeless.

extensions/Theme/themes/mydark/
├─ theme.json
├─ common.css
└─ vector.css

// theme.json
{
  "name": "MyDark",
  "description": "A simple dark theme for Vector and Timeless",
  "author": "Your Name",
  "license": "MIT",
  "styles": {
    "common": "common.css",
    "vector": "vector.css",
    "timeless": "vector.css"
  }
}

/* common.css */
.mw-body {
    background: #111;
    color: #ddd;
}
.mw-body a {
    color: #58a6ff;
}

/* vector.css – top bar */
.vector-header {
    background: #222;
    border-bottom: 1px solid #444;
}

Add to LocalSettings.php:

wfLoadExtension( 'Theme' );
$wgDefaultTheme = 'mydark';
$wgThemeSkins['mydark'] = [ 'vector', 'timeless' ];

Clear caches and you now have a clean, dark‑themed wiki.

Conclusion

Creating a custom CSS theme in MediaWiki gives you a clean separation between layout (the skin) and visual design (the theme). By using the official Theme extension, you keep your changes upgrade‑safe, enable per‑user overrides, and can target specific skins with minimal effort. Follow the steps above, test frequently, and enjoy a uniquely styled wiki that stays maintainable for years to come.