Open main menu


MediaWiki extensions manual
OOjs UI icon advanced.svg
Release status: stable
Implementation Skin
Description Allows you to use normal MediaWiki-pages as contents of your Sidebar
Author(s) MathiasErtltalk
Latest version 2.2.2 (2015-01-15)
MediaWiki >>1.27
Composer mediawiki/custom-nav-blocks
License GNU General Public License 3.0 or later
Download see #Download
Example in VoWi
Translate the CustomNavBlocks extension if it is available at
Check usage and version matrix.

The CustomNavBlocks extension allows you to customize your sidebar a lot further than what is possible with MediaWiki:Sidebar. With this extension each block is represented by its own page. That makes it possible to use any kind of element in your Sidebar, including images, numbered lists, nested lists, and so on. For example, this Wiki uses a vertical bar ('----') as a separator in the first block.


The source code of this extension is managed on GitHub. You can find the repository at mathiasertl/CustomNavBlocks. To get the most recent version of this extension, fetch the current HEAD:

git clone

Older versions are marked as tags, you can view available tags with git tag -l and move back to the current HEAD with git checkout <tag-name>. Versions for older versions of MediaWiki, if available, are managed as branches, use git branch and git checkout <branch> to move to a specific branch. To move back to the newest version, use git checkout master.

Note that Gitorious allows you to download older different commits as tarball if you do not want to install git.

Alternatively, the CustomNavBlocks.php file can be downloaded directly and then copied into the appropriate /extensions folder:



Download the CustomNavBlocks-extension and make the following adjustments to your LocalSettings.php:

require_once "$IP/extensions/CustomNavBlocks/CustomNavBlocks.php";
$wgCustomNavBlocksEnable = true;


After the extension is enabled, MediaWiki will look for a page called [[MediaWiki:CustomNavBlocks]]. This file defines the blocks used in the sidebar and has the following format:


In this example, the first block will be the content of MediaWiki:pagename with the title 'title' and the second block will be the content of MediaWiki:pagename2 with the title 'title2'. Please note that each line must not have more than one pipe ("|").

Next, you have to create the special pages and fill them with the content you want in your blocks. In the above example, create MediaWiki:Pagename and MediaWiki:Pagename2.

ExampleEdit has the extension enabled. The Sidebar-blocks are defined at MediaWiki:CustomNavBlocks, the first block is at MediaWiki:CustomBlockNavigation and so on.

Horizontal rows and the Vector skinEdit

The Vector skin doesn't look very good when a block contains a ----, which translates to a HTML element. To make good looking horizontal rows, that integrate well with the skin, we used CSS. First, no longer use WikiMarkup in your NavBlock:

first subsection
<div id="customnavblocks-subsection">
this section will have a <hr> above.

Then add the following CSS to MediaWiki:Monobook.css:

#customnavblocks-subsection {
    border-top: 1px solid #AAAAAA;
    margin-top: 0.1em;

... and MediaWiki:Vector.css:

#customnavblocks-subsection {
    background-position: left top;
    background-repeat: no-repeat;
    font-size: 0.75em;
    padding-top: 0.1em;

... note that you will have to change the URL to the one your wiki uses.


My wiki displays the normal sidebarEdit
  • Have you checked that you have included CustomNavBlocks.php in LocalSettings.php and set $wgCustomNavBlocksEnable to true? The Installation-chapter has a code-snippet that should work almost everywhere.
  • Does any line in MediaWiki:CustomNavBlocks contain more than one pipe ("|")?
  • Do all the pages defined in MediaWiki:CustomNavBlocks exist? If any page does not exist, the normal sidebar will be displayed.
upper-case block-titlesEdit

The MediaWiki-CSS (at least for the MonoBook skin) defines the titles of a block to be in lower-case. To override this behavior, edit MediaWiki:Common.css to include these lines:

.portlet h5 {
   text-transform: none;

You can of course set the text-transform property to any of the valid values.


2.2.1 (2012-10-07)Edit
  • Remove usage of deprecated functions.
  • Improve coding-style
  • Port to MediaWiki 1.18

This is almost a complete rewrite:

  • The extension now uses the SkinTemplateOutputPageBeforeExec-hook, which is available in MediaWiki 1.10.0 and later.
  • Thanks to that hook, you no longer have to patch MonoBook.php to get this working
  • The extension should now work completely independent of the MonoBook-theme.
  • The syntax of MediaWiki:CustomNavBlocks has changed a bit: To avoid ambiguities, each block is now written in its own line. This way both pagenames and blocktitles can contain spaces.
  • If anything goes wrong, the extension will break and display the normal sidebar.
  • The code of this extension wasn't changed for ages, but the patches for MonoBook.php change with each version of MediaWiki, since the line-numbers change.
  • first version documented here

1.16 StabilityEdit

I have tested this on my server and functions exactly as it does in 1.15 versions on my high-traffic wiki (1,500+ visitors a day). I used this over all three beta's and now the stable version, no problems whatsoever.


GPL 3.0 or later.

Sites Using this ExtensionEdit

See AlsoEdit