Tutorial:Beautiful MediaWiki URLs

This page is about configurating beautiful, pure URLs for MediaWiki, basically without any visible "index.php". The reasoning is that this syntax "index.php" is not interesting from the user’s point of view, and it’s ugly, so it shouldn’t be there.

This wiki implements these rules. Technically, this comes from CGI scripts, and this have to be taken into account to configure the server. Thereafter is the configuration to achieve that with nginx.

Prerequisites

• A server
• MediaWiki, in the directory, say, '/mediawiki'
• nginx, preferably with the module Lua

MediaWiki configuration

In the file LocalSettings.php, add the following directives at the end.

Remove the "script path" to remove all subdirectories.

$wgScriptPath = ;

Set the article path to its simplest form. With this, links to view the articles will be beautiful.

$wgArticlePath = '/$1';

Now, true improvements begin. When you view an article, the URL is beautiful, but it becomes again ugly when you edit an article or ask its printable form. So let’s remove the "index.php".

$wgScript = ;

The links for the actions have the form "/Main_Page?title=Main_Page&action=edit" for the edit action. You can remark the title is displayed twice. To remove this, we have to add a small hook in LocalSettings.php to remove the "title=" parameter.

$wgHooks['GetLocalURL::Internal'][] = 'urlPhpAgnostic';
function urlPhpAgnostic( &$title, &$url, $query ) {
    global $wgArticlePath;
    
    $url = str_replace( '$1', wfUrlencode( $title->getPrefixedDBkey() ), $wgArticlePath );
    
    while ( preg_match( '/^(.*&|)title=([^&]*)(&.*|)$/', $query, $matches ) ) {
        $query = $matches[1] . $matches[3];
    }
    
    if ( $query !=  ) {
        $url = wfAppendQuery( $url, $query );
    }
}

Nginx configuration

The basic skeleton is just below. We will then add 'location' directives.

server {
    
    listen 80;
    listen 443 ssl;
    server_name my-wiki.example;
    
    root /mediawiki;
    
    # 'location' directives to be added here
    
}

First, let’s add simple things: backend PHP scripts (I don’t search to hide them, they are backend so not viewed by human users).

location ~ ^/(api|load|opensearch_desc)\.php$ {
    include php5-fpm.conf;
}

Next, the more important thing: the call to index.php to catch all actions and transmit them to MediaWiki.

location / {
    if ($arg_title != ) {
        set_by_lua $mwredirect '
            local args = ngx.var.args
            local arg_title = ngx.var.arg_title
            arg_title = ngx.re.gsub(arg_title, "%3A", ":")
            arg_title = ngx.re.gsub(arg_title, "%20", "_")
            arg_title = ngx.re.gsub(arg_title, "[+]", "_")
            local url = "/" .. arg_title
            newargs, n, err = ngx.re.gsub(args, [[\btitle=[^&]*&?]], "", "jo")
            if string.len(newargs) > 0 then
                url = url .. "?" ..newargs
            end
            if string.sub(url, -1) == "&" then
                url = string.sub(url, 1, -2)
            end
                return url
        ';
        return 301 $mwredirect;
    }
    include php5-fpm.conf;
    fastcgi_split_path_info ^(/)(.*)$;
    fastcgi_param  SCRIPT_FILENAME  $document_root/index.php;
    fastcgi_param  PATH_INFO        $fastcgi_path_info;
}

The normal scenario, at the end of the location /, split the first part of the URL (only the slash) and the title of the article, transmitted to PHP/MediaWiki via the FastCGI parameter PATH_INFO. The first part of the location / rewrite remaining "title=" which can still be found in MediaWiki in the forms (Special:Recentchanges, Special:Log, etc.) -- AFAIK there is no way to improve this directly in MediaWiki without modifying the core (which is bad because it adds work for the updates).

Now, you should have a quite functional wiki, apart some missing images. Let’s add the UI images from the /skins subdirectory and the /extensions subdirectory at the same time (some extensions have JavaScript files or image files in their directories). Here are allowed only: the JS files, the images, the CSS and LESS files, and .htc files (used by IE).

location ~ ^/(extensions|skins)/ {
    location ~ \.(js|css|htc|less|png|svg|gif|jpg|xcf)$ {
        allow all;
        try_files $uri =403;
    }
    deny all;
}

Now we can allow integrated files of the /images subdirectory. Below are two variants depending if your wiki is public or private.

location ~ ^/images/ {
    # Publicly accessible files
    location ~ ^/images/(\.htaccess|README|lockdir.*)$ {
        return 404;
    }
    location ~ /$ {
        deny all;
    }
    try_files $uri =404;
    
    # Private files for a private wiki
    #include php5-fpm.conf;
    #fastcgi_split_path_info ^(/images/)(.*)$;
    #fastcgi_param  SCRIPT_FILENAME  $document_root/img_auth.php;
    #fastcgi_param  PATH_INFO        $fastcgi_path_info;
}

To finish, we can add /robots.txt and /favicon.ico if they are not managed by MediaWiki extensions.

location ~ ^/(robots.txt|favicon.ico)$ {
    try_files $uri =404;
}