Skip to main content

​
Installation

Ready to give your wiki a fresh look? Follow these steps to install Citizen.
Before you begin, ensure your MediaWiki installation meets the requirements.

​
Installation Methods

Choose the method that best fits your workflow:
The manual method is recommended for most users and production environments.
1

Download the skin

Download the latest release from GitHub.
2

Extract to skins directory

Extract the contents into a directory called Citizen in your MediaWiki skins/ folder:
cd /path/to/mediawiki
unzip mediawiki-skins-Citizen-main.zip
mv mediawiki-skins-Citizen-main skins/Citizen
Your directory structure should look like this:
mediawiki/
└── skins/
    └── Citizen/
        ├── skin.json
        ├── i18n/
        ├── includes/
        ├── resources/
        ├── templates/
        └── ...
3

Load the skin

Add this line to the bottom of your LocalSettings.php:
LocalSettings.php
wfLoadSkin( 'Citizen' );
4

Verify installation

Navigate to Special:Version on your wiki to verify that Citizen appears in the “Installed skins” section.

​
Activation

Once installed, you’ll need to activate Citizen as your wiki’s default skin.

​
Set as Default Skin

To make Citizen the default for all users, add this to your LocalSettings.php:
LocalSettings.php
$wgDefaultSkin = 'citizen';
The skin name must be lowercase in $wgDefaultSkin, even though the directory is capitalized.

​
Verify Activation

After saving LocalSettings.php, your wiki should now use the Citizen skin. You can verify this by:
  1. Visiting your wiki’s homepage
  2. Checking that the Citizen interface appears
  3. Confirming in Special:Version that Citizen is listed as the default skin

​
Configuration

Citizen works out of the box without additional configuration, but you can customize it to match your needs.

​
Basic Customization

Here’s a minimal configuration example:
LocalSettings.php
// Load and activate Citizen
wfLoadSkin( 'Citizen' );
$wgDefaultSkin = 'citizen';

// Set default theme
$wgCitizenThemeDefault = 'auto'; // 'light', 'dark', or 'auto'

// Customize theme color (mobile address bar)
$wgCitizenThemeColor = '#0d0e12';

// Enable features
$wgCitizenEnableCollapsibleSections = true;
$wgCitizenEnableCommandPalette = true;
$wgCitizenEnablePreferences = true;

​
Header Position

Customize where the header appears on desktop:
LocalSettings.php
$wgCitizenHeaderPosition = 'left'; // 'left', 'right', 'top', or 'bottom'

​
Progressive Web App

Enable PWA features for installable wiki apps:
LocalSettings.php
$wgCitizenEnableManifest = true;
$wgCitizenManifestOptions = [
    'background_color' => '#0d0e12',
    'theme_color' => '#0d0e12',
    'short_name' => 'MyWiki',
    'description' => 'My awesome wiki',
    'icons' => [
        [
            'src' => '/path/to/icon-192.png',
            'sizes' => '192x192',
            'type' => 'image/png'
        ],
        [
            'src' => '/path/to/icon-512.png',
            'sizes' => '512x512',
            'type' => 'image/png'
        ]
    ]
];
For a complete list of configuration options, see the Configuration Guide.
These extensions enhance Citizen’s features (all are optional):

PageImages

Adds images to search suggestion results (bundled with MediaWiki)

TextExtracts

Adds descriptions to search suggestions (bundled with MediaWiki)

ShortDescription

Adds short descriptions under page titles

TemplateStylesExtender

Allows CSS variables in TemplateStyles, including Citizen’s design tokens

​
Installing Extensions

LocalSettings.php
// PageImages and TextExtracts (bundled with MediaWiki)
wfLoadExtension( 'PageImages' );
wfLoadExtension( 'TextExtracts' );

// Configure Citizen to use them
$wgCitizenSearchDescriptionSource = 'textextracts';

​
Troubleshooting

  1. Verify wfLoadSkin( 'Citizen' ); is in LocalSettings.php
  2. Check that the Citizen directory exists in skins/
  3. Ensure skin.json is present in skins/Citizen/
  4. Clear your browser cache and MediaWiki cache
  5. Check file permissions (web server must be able to read the files)
  1. Check browser console for 404 errors
  2. Verify $wgResourceBasePath is set correctly in LocalSettings.php
  3. Clear MediaWiki’s resource cache: php maintenance/rebuildLocalisationCache.php
  4. Try accessing your wiki in an incognito/private window
Citizen includes skin styles for 70+ extensions that are automatically loaded. If an extension isn’t styled:
  1. Verify the extension is properly installed and loaded
  2. Check if the extension is supported
  3. The extension skin styles are defined in skin.json under ResourceModuleSkinStyles
  4. Consider contributing skin styles for unsupported extensions
  1. Verify $wgCitizenEnableCommandPalette = true; in LocalSettings.php
  2. Check browser console for JavaScript errors
  3. Ensure MediaWiki 1.43.0+ is installed (required for Codex components)
  4. Try disabling other skins/extensions that might conflict
If you encounter issues not listed here, please check the issue tracker or create a new issue with details about your environment.

​
Updating

Keep Citizen up to date to get the latest features and fixes:
  1. Download the latest release
  2. Back up your current skins/Citizen/ directory
  3. Extract and replace with the new version
  4. Clear MediaWiki cache: php maintenance/update.php

​
Next Steps

Now that Citizen is installed, explore these resources:

Configuration

Customize colors, layout, and features

Extension Support

Learn about styled extensions

Customization

Theming and personalization options

Contributing

Help improve Citizen

Build docs developers (and LLMs) love

Get started for freeTalk to us