Setting Up Custom Skins in MediaWiki: A Developer's Guide

Why Bother with a Custom Skin?

Honestly, the default Vector skin is fine for most wikis, but there’s something oddly satisfying about seeing your own logo perched at the top‑left, or a colour palette that matches your community’s vibe. A custom skin can be a quiet bragging‑right, a branding tool, and—if you’re feeling adventurous—a low‑key way to dip your toes into MediaWiki’s PHP‑heavy guts without drowning.

When I first tried to tinker with a skin, I thought, “Just copy Vector, rename a folder, change a few CSS rules, and call it a day.” Spoiler: It’s not that simple, but the journey is worth the occasional “aha!” moment. Below is a no‑fluff, hands‑on walk‑through that tries to keep the jargon to a minimum while still covering the nuts and bolts you’ll need.

Prerequisites (Don’t Panic, It’s Light)

• Access to a MediaWiki installation (local box or a dev VM works).
• Basic familiarity with PHP, HTML, and CSS. If you can write a div tag, you’re good.
• Shell/command‑line access to create files and run composer if you need to pull in ext-skin dependencies.
• A dash of curiosity—preferably a cup of coffee on the side.

Step 1: Sketch the Vision (Or Just Wing It)

Before you open any editor, grab a scrap of paper (or a digital note) and doodle how you want the header, navigation tabs, and content area to behave. Do you want a sticky top bar? A dark mode toggle? Jot those ideas down. This isn’t a design brief for a Fortune‑500 client; it’s a personal map to keep you from wandering aimlessly in the codebase.

Step 2: Boilerplate – Grab a Starter Skin

MediaWiki ships with a skin skeleton you can clone. Run this in your wiki’s skins/ directory:

cd /path/to/mediawiki/skins
git clone https://gerrit.wikimedia.org/r/mediawiki/skins/Vector.git MyCoolSkin

Rename the folder to whatever you like—say, MyCoolSkin. Inside, you’ll see a MyCoolSkin.php file (the entry point) and a resources/ folder housing CSS, JS, and images.

Step 3: Rename the Namespace

Open MyCoolSkin.php. You’ll find a class definition that reads class SkinVector extends SkinTemplate. Change every occurrence of Vector to MyCoolSkin. Also, rename the PHP file itself to match the class, e.g., MyCoolSkin.php. It’s a bit of a copy‑paste dance; watch out for stray Vector strings in comments—they’re harmless but can be confusing later.

Step 4: Tell MediaWiki About Your New Skin

Add a line to LocalSettings.php:

// Register the skin
wfLoadSkin( 'MyCoolSkin' );

Optionally, set it as the default for logged‑in users:

$wgDefaultSkin = "mycoolskin";

Notice the lower‑case name for the variable—MediaWiki loves those.

Step 5: Tweak the HTML Template

The real visual changes happen in MyCoolSkinTemplate.php (or whatever you rename it to). This file contains the execute() method that spits out the page skeleton. Feel free to rearrange sections, add a new <div> for a banner, or drop in a quirky quote.

Example snippet to insert a custom tagline below the site title:

<!-- Inside execute() just after the site title -->
<div class="mycoolskin-tagline">
   <em>Your wiki, your voice, your style.</em>
</div>

Don’t forget to add a matching CSS rule in resources/mycoolskin.css:

.mycoolskin-tagline {
    font-size: 0.9rem;
    color: #555;
    margin-top: 0.3em;
    text-align: center;
}

Step 6: Load Your CSS/JS Properly

MediaWiki uses ResourceLoader to bundle assets. In extension.json (create one if it doesn’t exist), register your files like so:

{
    "ResourceModules": {
        "skins.mycoolskin": {
            "styles": [
                "resources/mycoolskin.css"
            ],
            "scripts": [
                "resources/mycoolskin.js"
            ],
            "position": "top"
        }
    }
}

Then, in MyCoolSkin.php, tell the skin to load the module:

public function initPage( OutputPage $out ) {
    parent::initPage( $out );
    $out->addModuleStyles( 'skins.mycoolskin' );
}

Step 7: Test, Tweak, Repeat

Clear the cache (php maintenance/eval.php "wfResetOutputCache()" or just purge a page) and reload. You might see a broken layout or a missing image—no surprise. Open the browser’s dev tools, inspect the offending element, and adjust the CSS. This back‑and‑forth feels a bit like polishing a stone; you’ll eventually see the sparkle.

Advanced Bits (Optional, But Fun)

Dark Mode Switch

Adding a dark mode toggle can be as simple as toggling a class on the body element. Here’s a tiny JavaScript snippet you can drop in resources/mycoolskin.js:

// Simple dark mode toggle
document.addEventListener('DOMContentLoaded', function() {
    const btn = document.createElement('button');
    btn.textContent = '🌙';
    btn.style.position = 'fixed';
    btn.style.bottom = '1rem';
    btn.style.right = '1rem';
    btn.addEventListener('click', () => {
        document.body.classList.toggle('mycoolskin-dark');
    });
    document.body.appendChild(btn);
});

And the accompanying CSS:

.mycoolskin-dark {
    background:#111;
    color:#ddd;
}
.mycoolskin-dark a { color:#9cf; }

That single button can give your wiki a nocturnal makeover without any heavy‑weight theming frameworks.

Locale‑Specific Adjustments

If your community spans a few languages, you might want to change the navigation order based on $wgLang. In MyCoolSkinTemplate.php you can do something like:

if ( $this->getSkin()->getLanguage() === 'fr' ) {
    // Swap “Recent changes” and “Talk” tabs for French users
    $this->data['content_navigation']['namespaces']['talk'] = $this->msg('talk')->text();
}

It’s a tiny touch, but it shows you’re listening to the audience—nothing fancy, just a bit of empathy in code.

Hook into Page Rendering

Sometimes you want to inject something after the main article content (like a disclaimer). Use the BeforePageDisplay hook in extension.json:

{
    "Hooks": {
        "BeforePageDisplay": "MyCoolSkinHooks::onBeforePageDisplay"
    }
}

And the PHP handler:

class MyCoolSkinHooks {
    public static function onBeforePageDisplay( OutputPage &$out, Skin &$skin ) {
        $out->addHTML( '<div class="mycoolskin-disclaimer">Please verify information before citing.</div>' );
        return true;
    }
}

Now every page gets a gentle reminder—perfect for wikis that host crowdsourced data.

Common Pitfalls

• Cache confusion: MediaWiki loves caching. If you make CSS changes and see nothing, run php maintenance/purgeList.php --flush or add ?action=purge to the URL.
• Namespace clashes: Don’t name your skin “Vector” or any existing core skin. MediaWiki will silently ignore your files, leading to head‑scratching moments.
• Missing ResourceLoader module: Forgetting to register the module in extension.json results in “Resource not found” errors in the console.
• PHP syntax slips: A stray semi‑colon or missing curly brace can break the entire site. Use php -l filename.php to lint before reloading.

Where to Go From Here?

If you’ve gotten this far, congratulations—you’ve built a functional, albeit simple, custom skin. The next logical steps might be:

1. Publish the skin on MediaWiki’s skin directory so others can benefit.
2. Integrate Sass or Less for more flexible styling, especially if your community likes to experiment with colour schemes.
3. Write a short “How‑to” video; seeing the skin change in real‑time can be a great onboarding tool for new contributors.

Final Thought

Custom skins are not about reinventing the wheel; they’re about giving your wiki a little personality that reflects the people who use it. A dash of CSS, a pinch of PHP, and a sprinkle of creativity can turn a bland interface into a space that feels “home‑grown.” So, roll up those sleeves, fire up your editor, and let the skin‑crafting adventure begin.