Enhancing MediaWiki with Custom Skins

Not every wiki needs a custom skin — most custom branding is achievable with configuration and CSS alone, which has a big advantage: those customizations survive upgrades and never break the editing interface. This article is the pragmatic path to restyling MediaWiki (skins, CSS and options) before you even consider writing a skin from scratch. If you do end up building one, the companion article on this blog covers the skin architecture itself.

1. Pick the right base skin

MediaWiki ships Vector (default), Timeless, MonoBook and Minerva. Community skins add design flourishes without custom code:

• Citizen — modern design, dark mode, good for documentation and non-Wikipedia-looking wikis
• Chameleon — Bootstrap-based, fully configurable via wiki pages, no extension code
• Timeless — responsive and a sensible base if you want a custom look but keep the default editor

2. Skin options and configuration

Choose the default skin and what users may pick:

$wgDefaultSkin = 'citizen';
$wgSkipSkins = [ 'monobook' ];  // hide skins from the preference list

Vector 2022 and most modern skins expose design-token customization through SkinModule features and per-skin options — check the skin's own page for its configuration variables (e.g. Citizen offers $wgCitizenThemeDefault and sidebar options). For Vector, skin.json-driven options like wgVectorMaxWidth control layout without touching PHP.

3. Site-wide CSS: the workhorse

Three MediaWiki system messages inject CSS on every page:

• MediaWiki:Common.css — all users, all skins
• MediaWiki:Vector.css / MediaWiki:Timeless.css — per-skin overrides
• MediaWiki:Group-user.css (and -sysop.css, etc.) — per user group, e.g. show admin-only styling

Example — brand colors and a constrained reading width:

/* MediaWiki:Common.css */
:root {
  --color-base: #1a1a1a;
}
#content {
  max-width: 48rem;
  margin-inline: auto;
}

The Wikimedia design system exposes CSS custom properties (color and spacing tokens) that sites can override — this is how dark themes are implemented on top of default skins.

4. Logo and favicon

Replace the logo without any CSS via configuration:

$wgLogos = [
    '1x' => 'https://example.org/logo.png',
    'svg' => 'https://example.org/logo.svg',
];
$wgFavicon = 'https://example.org/favicon.ico';

Note: the old $wgLogo string form still works but is deprecated — use $wgLogos with the svg/1x/2x keys (or wordmark, icon for modern skins).

5. The upgrade-proof way to add features

Resist editing skin files directly — the next MediaWiki upgrade overwrites them. Three safe places for behavior changes:

1. JavaScript — MediaWiki:Common.js runs on every page and has access to mw APIs; small helpers (collapsible custom elements, UI tweaks) belong here
2. TemplateStyles — per-template CSS with <templatestyles src="..."/>, scoped and sanitized; ideal for styling infoboxes and navigation templates without polluting Common.css
3. Sidebar and footer — MediaWiki:Sidebar controls navigation; SkinAddFooterLinks hook or MediaWiki:Footer-text variants handle footers

6. Testing before going live

1. Preview as a visitor: ?useskin=citizen on any URL renders with that skin regardless of preferences — useful for screenshots and reviews
2. Test a new default with $wgDefaultSkin on a staging copy first; users can always override per account
3. Check dark-mode support and print CSS — the two things readers notice most when a restyle breaks

Start with the base skin, spend the effort on Common.css and brand tokens, and only reach for a custom skin when layout (not color) is the problem. CSS-and-config first keeps the wiki upgradeable, and that is worth more than any pixel-perfect theme.