By MW in mediawiki — 18 Feb 2024

Customizing MediaWiki Skins for Better User Experience

Why skinning matters more than you think

Ever opened a wiki on your phone and seen that clunky, Wikipedia‑style bar that forces you to pinch‑zoom? You’re not alone. The visual layer—what MediaWiki calls a skin—is the first thing users stare at, and if it screams “legacy” before they even read a line, the chances of them sticking around plummet.

That’s why tweaking, or fully re‑designing, a skin can feel like the difference between a bustling knowledge hub and a dusty archive. Below is a no‑fluff, step‑by‑step dive into customizing MediaWiki skins for a smoother, more intuitive user experience.

Pick a solid foundation before you start painting

MediaWiki ships with a handful of built‑in skins (Vector, Monobook, Timeless, etc.). Most admins reach for Vector because it looks familiar, but the reality is that it doesn’t play nicely on small screens without a fair amount of work. Recent community chatter, like the Reddit thread on responsive skins, points to Medik as a clean, mobile‑first alternative that still feels “wiki‑ish”.

Here’s a quick sanity check:

Does the skin already use ResourceLoader for CSS/JS? If yes, you’ll have an easier time injecting your changes.
Is the base skin actively maintained? Look for a recent commit on its GitHub repo or a fresh entry on the ProWiki “Best MediaWiki Skins” list.
Do you need a left‑hand navigation bar, or would a top‑only menu suffice? Some skins lock you into a layout that’s hard to break without digging into PHP templates.

If the answer to all three is “yes”, you’ve got a decent starting point. If not, consider forking a responsive skin like Medik or Citizen and treating it as your canvas.

Layer 1: CSS overrides via user subpages

MediaWiki lets any logged‑in user add skin‑specific CSS by creating a subpage on their user page. In practice, most site‑wide tweaks are done on the MediaWiki:.css page (you need sysop rights).

Example: you want to enlarge the edit button and give it a gentle teal background.


/* MediaWiki:Vector.css */
#ca-edit a {
    background:#e0f7fa;
    padding:6px 12px;
    border-radius:4px;
    font-weight:bold;
}

Save that page, clear your cache (or add ?action=purge to the URL), and you’ll see the change instantly. It’s a tiny move, but cue alone can nudge newcomers toward contributing.

Layer 2: Hooking into ResourceLoader for smarter assets

When you start stacking a bunch of CSS rules, the page load can inch slower. ResourceLoader bundles and minifies assets on the fly, but you have to tell it about your new files. That’s where a tiny LocalSettings.php snippet comes in.


# LocalSettings.php
$wgResourceModules['ext.mySkin.custom'] = [
    'styles' => [
        'skins/MySkin/custom.css' => [ 'media' => 'screen' ],
    ],
    'position' => 'top',
    'targets' => [ 'desktop', 'mobile' ],
];
$wgHooks['BeforePageDisplay'][] = function ( OutputPage $out ) {
    $out->addModules( 'ext.mySkin.custom' );
    return true;
};

Notice the targets line – it forces the same CSS to hit both desktop and mobile, avoiding the dreaded “mobile‑only style missing” bug that crops up in half‑baked skins.

Layer 3: Taming the template files (Smarty, PHP, or Mustache?)

If your skin uses PHP template files (.php in the templates/ folder), you can rearrange the markup to suit your UI goals. A common gripe is that breadcrumbs sit too low on the page, crowding the title. Move them up with a few lines.


// skins/MySkin/templates/MainPage.php
// Original snippet
<div id="content">
    <div id="siteSub">{{{sitename}}}</div>
    <h1 id="firstHeading">{{{title}}}</h1>
    // ...
</div>

// Revised snippet – breadcrumbs before content
<div id="breadcrumbs">{{{breadcrumb}}}</div>
<div id="content">
    <h1 id="firstHeading">{{{title}}}</h1>
    // ...
</div>

That tiny re‑order makes the navigation path visible sooner, a win especially for users who skim pages on a phone. Just remember to clear the parser cache after any template change.

Layer 4: Adding a touch of JavaScript for interactivity

Sometimes subtle UX improvements need a sprinkle of JS—think collapsible sidebars or a “back to top” button that appears only after scrolling. MediaWiki’s ResourceLoader also handles JS modules.


// skins/MySkin/modules/backToTop.js
document.addEventListener('DOMContentLoaded', function () {
    var btn = document.createElement('button');
    btn.textContent = '↑ Top';
    btn.id = 'backToTop';
    btn.style = 'position:fixed;bottom:20px;right:20px;display:none;';
    document.body.appendChild(btn);
    window.addEventListener('scroll', function () {
        btn.style.display = (window.scrollY > 300) ? 'block' : 'none';
    });
    btn.addEventListener('click', function () {
        window.scrollTo({ top: 0, behavior: 'smooth' });
    });
});

Hook it up in LocalSettings.php just like the CSS module, and you’ve added a small, yet appreciated, quality‑of‑life feature.

Testing for responsiveness – the oft‑ignored step

It’s easy to get lost in code and forget the ultimate goal: a smooth experience on every screen size. Here’s my quick checklist:

Open the wiki in Chrome DevTools, toggle device toolbar, and scroll through the most common breakpoints (320 px, 768 px, 1024 px).
Make sure navigation toggles (the “hamburger” icon) actually opens the menu; if not, inspect the aria‑expanded attribute – a missed toggle is a common accessibility slip.
Zoom in to 150 % on a desktop; look for any “overflow‑hidden” containers that truncate long page titles.
Grab a friend—maybe a non‑techy colleague—and ask them to find the “Edit” button on a random article. Their confusion is gold for spotting hidden UX flaws.

Common pitfalls and how to dodge them

Over‑specific selectors – writing CSS like #content > div > ul > li > a works until a future MediaWiki update reshuffles the DOM. Favor class‑based hooks that you control, e.g., .my-skin‑nav a.

Hard‑coding pixel values – a width: 960px sidebar fine on a laptop but breaks on a tablet. Use max‑width: 100% and Flexbox or CSS Grid instead.

Neglecting cache busting – after you push new CSS, browsers might cling to the old file. Append a query string like ?v=202509 to the module definition or clear the CDN cache.

And, of course, don’t forget the localization strings. If you rename a button or rearrange a menu, update the i18n/*.json files so translators aren’t left with orphaned messages.

Tips for a genuinely better user experience

Prioritize readability: a line‑height of 1.5 and a comfortable font size (16 px on mobile) make long articles less tiring.
Breadcrumb visibility: place them near the top, use a muted background, and keep them clickable.
Consistent action colors: make “Save” green, “Cancel” gray, and stick to that palette across the whole site. Humans notice color cues faster than text.
Feedback on actions: a tiny toast notification (“Page saved”) reassures users that their edit succeeded.
Keyboard navigation: ensure tabindex order follows visual flow; a broken tab order is a silent barrier for power users.

Wrap‑up thoughts

If you’ve ever brushed past a wiki because it felt “cl have a toolbox to turn that clunk into a sleek, approachable interface. The journey starts with picking a responsive skin, layers on CSS overrides, then nudges the HTML markup and JavaScript just enough to feel modern without breaking existing extensions.

Remember: the best user experience isn’t a one‑off cosmetic polish; it’s an ongoing habit of watching real users interact, catching the little irritations, and iterating. And if your wiki ever needs a fresh coat, you already know where to startright in the skin’s .css, .php, and .js files, guided by the principles above.