Manual:Short URL


 * See Manual:Short URL overview if you find below confusing

According to Tim Berners-Lee, good URLs should never change. Short URLs that hide PHP mechanics from the browser location bar for normal pages are good user interface.

These short URLS are not implemented in MediaWiki by default because they are done in concert with Web server configurations that can get complicated and may vary depending on the specific Web server being used.

In all the examples, it is assumed that MediaWiki is installed in the directory located at  and that you want to use   as an alias for. It is possible to use an alternative install directory and an alternative alias simply by changing these values ("wiki" and "w") in the examples below. The process is slightly more complicated if you want both to be the same, or if you want the alias to be the root directory ("" instead of "wiki"), but in both cases it is possible with a bit of tweaking (and a few usage restrictions).

No root access
These methods assume that you don't have access to the server configuration (for example, if you're on a shared host); if you do, see 'Root access' below. You can use an alias or a rewrite, but preferably not both.

Alias
You can set an alias in .htaccess, so that the server will invisibly replace "wiki" with "w/index.php".


 * Alias is not allowed in .htaccess files, at least on Apache 2.0, or did I miss something? See the Alias Directive documentation.

Solution without Alias
I struggled for a few hours and have found this solution. My site (http://www.eroswiki.com) is in ~/eroswiki/wiki. Using this .htaccess in my ~/eroswiki directory, I was able to use short URLs and the redirection I wanted. My site is hosted at 1 & 1.

In ~/web_root/.htaccess RewriteEngine On RewriteCond %{HTTP_HOST} ^domain.com RewriteRule ^(.*)$ http://www.domain.com/$1 [r=301,L] RedirectMatch ^/$ http://www.domain.com/wiki RewriteCond %{REQUEST_URI} ^/wiki$ RewriteRule ^(.*) /wiki/index.php?title=Main_Page [L]
 * 1) Redirect http://domain.com to http://www.domain.com

RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^wiki/(.*) wiki/index.php?title=$1 [PT,L,QSA]

In ~/web_root/wiki/LocalSettings.php

Rewrite
You can rewrite the URL, so the server will invisibly load "w/index.php?title=article" for "wiki/article".

Root access
These methods require that you have access to the server configuration. If you are on a shared host, you most likely don't; see 'No root access' above.

Using aliases in httpd.conf
This is the prefered method from a performance point of view, but requires access to edit httpd.conf. Most shared hosting systems do not allow changes to httpd.conf. The method below has been tested successfully with MediaWiki 1.4.4.

1. In LocalSettings.php, make sure you are using these default values: If you put the wiki installation in a subdirectory such as /w, use $wgScriptPath = "/w" as appropriate.

If you put the files (such as index.php) in the root, you can use $wgScriptPath = "" in LocalSettings.php.

2. In LocalSettings.php, set the following: '''Remember, the virtual directory for the wiki article space should never, ever overlap or hide real files. In particular it should never, ever overlap your base installation directory or the root directory. It can be a virtual subdirectory, such as /wiki.''' (For example: do not try to rewrite "/wiki/Article" to "/wiki/index.php?title=Article).

3. Set up the following alias in your Apache httpd.conf. It can be in a  section, or in "Aliases" section, or in your general site config. In this alias, the prefix  represents the path you installed to &mdash; the directory where MediaWiki's   lives. Replace the prefix as appropriate for your actual file system path.

Alias /wiki "/filesystem/path/to/my/site/index.php" Alias /index.php "/filesystem/path/to/my/site/index.php"
 * 1) These must come last, and in this order!

For example:

Alias /wiki "c:/apache/www/w/index.php" Alias /index.php "c:/apache/www/w/index.php"

After making modifications to httpd.conf, you might have to restart Apache to apply the changes.

Apache rewrite
If the Alias method is not suitable (for example, you use PHP as a CGI), you can use Apache mod_rewrite rules instead. mod_rewrite is an Apache module which allows certain request URLs to be changed into other URLs. mod_rewrite is fairly powerful, and also fairly complicated, but for short URLs only a simple rule is required. You can read the full mod_rewrite manual here.

Make sure Apache loads the Rewrite module. In httpd.conf this line must be added/uncommented: LoadModule rewrite_module modules/mod_rewrite.so

After making modifications to httpd.conf, you might have to restart Apache to apply the changes.

If you are using Apache 2, you might also need to turn on. It is on by default in a standard installation of Apache and PHP, but some vendors/packagers may have it disabled on your system.


 * This fix has known problems with httpd-2.0.40-21 on Redhat Linux systems. See the talk page for details.

Lighttpd rewrite
Example configuration: Then there are two things needed to change in two files:
 * wiki is installed in /w/ direcotry in http root dir.
 * you want to avoid index.php
 * you want to access articles as /wiki/Article
 * lighttpd.conf
 * enable mod_rewrite in server modules
 * add below code as rewriting:

url.rewrite-once = (    "(^/wiki/[^:]*[\./].*)" => "$1",     "^/wiki/([^?]*)(?:\?(.*))?" => "/w/index.php?title=$1&$2",       ) After restarting lighttpd it should work. The code is not fully rewriting the code cause pages lik Linking to this page or Printable version etc are linked to /w/index.php?... anyway. So this code requires tweaking by more experienced users.
 * now edit /w/LocalSettings.php

Subdomain with Subdirectory in Article URL
You can make MediaWiki use a subdomain like "wiki.example.com/foo". This assumes that you already have a subdomain ready; if not, set one up or contact your host.


 * 1) Use one of the methods above to reduce "/wiki/index.php?title=foo" to "/wiki/foo".
 * 2) Add $wgServer to LocalSettings.php with your subdomain.
 * 3) Blank the value of $wgScriptPath</tt> in LocalSettings.php, so that MediaWiki links to the domain.

Two Subdomains with no Subdirectory in Article URL
''Although a neat looking solution, this didn't work for Martin Cleaver using 1.10 - the urls generated failed to save pages.

This approach to shortening article URLs uses two subdomains: one for short article URLs, the other for all other files and "permanent" article URLs. For example, http://wiki.example.com/Article_Title is the url for an article, and http://static.wiki.example.com/wiki/index.php is where the index file is actually located. The trick to doing this is to use directory rewriting, and the 'wgArticlePath' and 'wgScriptPath' variables.


 * 1) Set up your subdomains pointing to two directories such as /var/www/wiki</tt> and /var/www/wikistatic</tt> for http://wiki.example.com/ and http://static.wiki.example.com respectively.
 * 2) Install the wiki files in the /var/www/wikistatic/wiki</tt> directory. (Standard short URL techniques can be used in that directory as well, if required. You could also not use the "wiki" directory, and put the files directly in the subdomain's root directory, removing the "/wiki" and "wiki/" from the LocalSettings.php</tt> and index.php</tt> files below.)
 * 3) In the LocalSettings.php</tt> file, make the changes shown below.
 * 4) In the /var/www/wiki</tt> directory, place two files, "index.php" and ".htaccess", as shown below.

LocalSettings.php
/var/www/wikistatic/wiki/LocalSettings.php</tt>

Note: these lines may be interspersed among others. If these variables are not in the file, add them in.

index.php
/var/www/wiki/index.php</tt> The meaning of the two middle lines are:
 * 1) Set the working directory to that of the other subdomain (replace that path with the correct absolute path to the MediaWiki files your server).
 * 2) Include the index.php file from that directory.

.htaccess
/var/www/wiki/.htaccess</tt> RewriteEngine On RewriteBase / RewriteRule ^.*$ index.php?title=$0 [L,QSA]

The meaning of these three lines are:
 * 1) Enable URL re-writing
 * 2) Tell the re-writer that we are using the root directory of the subdomain
 * 3) Send all requests to the index.php file (in this directory/subdomain)

Please note: This is a hack, and the MediaWiki documentation does not seem to say anything about having full URLs including domain names in the wgScriptPath</tt> and wgArticlePath</tt> variables, but it appears to work in version 1.9.3. The only problem should be if any pages prefix wgServer</tt> onto either of the two variables shown above in LocalSettings.php.

The http://static.wiki.example.com subdomain eliminates the problems with the other subdomain approaches, because the filenames that would conflict there are in a totally different namespaces when using this approach.

Subdomain with no Subdirectory in Article URL
If you want to use something like http://wiki.example.com/Article_Title, make the following changes to .htaccess</tt> and LocalSettings.php</tt> after installing. These instructions assume MediaWiki is installed to <tt>wiki/</tt>, the subdomain is only for the wiki, and that the main page is Main_Page. <tt>.htaccess</tt> lines are pretty much exactly what the owner of http://www.muscatelli.info/ posted on the discussion page.

.htaccess
The first step is to make sure that requests for /Article_Title get interpreted correctly. The following lines should be added to .htaccess in the root of the wiki.example.com domain:

RewriteEngine On RewriteRule ^[^:]*\. - [L] RewriteRule ^[^:]*\/ - [L] RewriteRule ^/*$ /wiki/index.php?title=Main_Page [L,QSA] RewriteRule ^(.+)$ /wiki/index.php?title=$1 [L,QSA]
 * 1) anything that contains a dot without a colon should be left alone
 * 1) anything that contains a slash without a colon should be left alone
 * 1) redirect to main page
 * 1) anything else is to be treated as a title

LocalSettings.php
Now that URLs like http://wiki.example.com/Article_Title work, all that remains is to tell MediaWiki to use those URLs. This is done by defining <tt>$wgArticlePath</tt> in <tt>LocalSettings.php</tt>. Here's an example, defined just after <tt>$wgScriptPath</tt>:

Subdomain with no Subdirectory in Article URL using mod-rewrite
Apache's mod-rewrite can be used to allow the shortest URL's of just http://yourdomain/pagename. Mod-rewrite changes the illegally formatted "friendly" URL request into a legitimate request directed at the index.php script like usual. To use mod-rewrite, specify a condition pattern, and a transformation rule to apply to the URL if it matches the condition pattern, such as in the following example: RewriteEngine On   RewriteCond %{REQUEST_URI} !^/w.*/ RewriteRule ^/(.*) /wiki/index.php/$1 [L] This re-write condition says not to touch any URL's which start with a lowercase W and start and finish with a forward slash, this protects all old-style article requests, and requests to internal MediaWiki files like scripts or images. By not specifically using the term wiki in the condition allows other directories of web documents outside the wiki such as /www/media

The re-write rule then assumes everything after the leading slash to be an article name and reformats the URL accordingly. Also <tt>$wgArticlePath = "/$1"</tt> is set in LocalSettings.php to make the friendly form the default way of rendering links. Links involving a query-string will use the usual format.

This uses the technique for evading the Manual:Short URL described below.

Subdomain with no Subdirectory in Article URL using Lighttpd
To put MediaWiki in a root directory with the Lighttpd webserver, use the following rule (assuming mod_rewrite is loaded):

url.rewrite-once = (   "(^/[^:]*[\./].*)" => "$1",    "^/([^?]*)(?:\?(.*))?" => "/wiki/index.php?title=$1&$2", )

If you want to host this on a seperate domain (which is very likely for a wiki in the root-dir) do:

$HTTP["host"] == "wiki.example.com" { server.document-root = "/path/to/webroot" url.rewrite-once = (       "(^/[^:]*[\./].*)" => "$1",        "^/([^?]*)(?:\?(.*))?" => "/wiki/index.php?title=$1&$2",    ) }

If you want to allow ampersands in titles too (or any other character that might be considered an argument delimiter in the query string) you can make a more complicated rule using mod_magnet. For more information, see lighttpd's documentation about mod_magnet on their website.

Enabling a wiki on the root URL, a secondary wiki, and a rails app using Apache Rewrite
This shows how to enable a wiki on the root URL, a secondary wiki on a descendant URL, and a rails app with clean structure.

Example URL structure http://example.com/ http://example.com/wiki_main/index.php?title=Main_Page http://example.com/Special:Recentchanges http://example.com/wiki_main/Special:Recentchanges http://example.com/wiki_main/index.php?title=Special:Recentchanges
 * Primary wiki - Main page
 * Primary wiki - Special:Recentchanges

http://example.com/wiki_other/Main_Page http://example.com/wiki_other/index.php?title=Main_Page
 * Secondary wiki - Main page

http://example.com/wiki_other/Special:Recentchanges http://example.com/wiki_other/index.php?title=Special:Recentchanges
 * Secondary wiki - Special:Recentchanges

http://example.com/weblog/ http://example.com/weblog/controller
 * Rails application

Pertinent directory structure web/ example_com/ cgi-bin/ htdocs/ .htaccess weblog -> ../rails/public weblog.html wiki_main/ .htaccess LocalSettings.php [usual mediawiki files] wiki_other/ .htaccess LocalSettings.php [usual mediawiki files] rails/ blogapp/ .htaccess app/ config/ db/ public/ vendor/

<tt>weblog</tt> is a symbolic link to <tt>/web/example_com/rails/blogapp/public</tt>.

Contents of <tt>/web/example_com/htdocs/.htaccess</tt> Options FollowSymLinks RewriteEngine On

RewriteCond %{REQUEST_URI} ^/Main_Page RewriteRule ^(.*) / [R,L]
 * 1) Hide Main_Page from URL

RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_URI} !^/wiki_main/ RewriteRule ^(.*) /wiki_main/index.php/$1 [L]
 * 1) If the file is real, skip this rule

RewriteRule ^$ /wiki_main/index.php/Main_Page  [PT,L]
 * 1) http://example.com displays the front page of the primary wiki

Options FollowSymLinks RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.+)$ index.php?title=$1 [L,QSA]
 * Contents of <tt>/web/example_com/htdocs/wiki_main/.htaccess</tt>
 * Contents of <tt>/web/example_com/htdocs/wiki_other/.htaccess</tt>

Modifications to <tt>/web/example_com/htdocs/wiki_main/LocalSettings.php</tt> $wgArticlePath = "/$1";

Modifications to <tt>/web/example_com/htdocs/wiki_other/LocalSettings.php</tt> $wgArticlePath = "$wgScriptPath/$1";

Contents of <tt>/web/example_com/htdocs/weblog.html</tt>

<meta http-equiv="Refresh" content="0; url=http://example.com/weblog/" />

IIS6 and ShortURL support
IIS6 requires an ISAPI URL Rewrite filter to work. Several commercial filters are available. An open source ISAPI filter is available for free from http://www.codeplex.com/IIRF called Ionic's Isapi Rewrite Filter (IIRF). As of August 2007, IIRF version 1.2.12c is known to work with MediaWiki 10.1 using IIS6 under Windows Server 2003 SP1. It is likely that other IIS implementations are supported, as IIRF is also IIS 5.0 (Windows 2000) and IIS 5.1 (Windows XP) compatible.
 * Installation instructions are available from IIRF's website in the download package.
 * IIRF has a comprehensive forum providing install support.
 * To successfully configure IIRF, an INI file must be customized for MediaWiki. See below for details.

Sample INI file code for MediaWiki at wiki.domain.com/wiki/: (IsapiRewrite4.ini, stored in same path as IsapiRewrite4.dll) RewriteLog c:\temp\iirfLog.out RewriteLogLevel 3 MaxMatchCount 1 RewriteEngine On

RewriteCond %{HTTP_HOST} ^wiki.domain.com
 * 1) Change to suit your domain

RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d
 * 1) Checks for local file existance so that .css, .js and other MediaWiki files aren't processed

RewriteRule ^/wiki/(.*)$ /wiki/index.php?title=$1 [I,L] IterationLimit 4

See also: URL rewrite in IIS

Prevent bots from crawling index.php
You can make sure that search engines only index actual wiki pages, without indexing action views (such as edit or history pages, with URLs in the form ). Note that doing this without implementing short URLs will block all pages from being indexed.

Create a file named <tt>robots.txt</tt> in the root of your MediaWiki installation with the following content. User-agent: * Disallow: /index.php

Ignoring the Trailing slash
When a page is accessed with a trailing slash MediaWiki sees it as a different page - (Named <tt>Page/</tt> instead of <tt>Page</tt>). You may want to consider this solution.

~/web_root/.htaccess
Options FollowSymLinks RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.+)$ index.php?title=$1 [L,QSA]

~/web_root/LocalSettings.php
$wgArticlePath = "$wgScriptPath/$1"; $GLOBALS['_REQUEST']['title'] = preg_replace("/^(.+)\/$/", "$1", $GLOBALS['_REQUEST']['title']);

Allowing for escaped characters in URI
It may happen that you only have access to the <tt>.htaccess</tt> file, and you would like to allow special characters such as <tt>+</tt> in the article title, and you are using Apache 2.x. LocalSettings.php therefore contains

~/web_root/w/LocalSettings.php
while <tt>.htaccess</tt> contains something like

~/web_root/.htaccess
RewriteEngine on RewriteBase /

RewriteRule ^wiki$ wiki/Main_Page [R,NC] RewriteRule ^wiki/$ wiki/Main_Page [R,NC]

RewriteCond %{THE_REQUEST} ^[A-Z]+\ /wiki/([^?\ ]+) RewriteRule ^wiki/(.+)$ /w/index.php?title=%1 [NE,L,QSA]

The use of <tt>RewriteCond %{THE_REQUEST}...</tt> catches the query before Apache and PHP conspire to replace <tt>%2B</tt> in the URL with a space.

Repeated directory errors
Should you receive looping alias/rewrite errors such as: 'Cannot find page www.example.com/wiki/wiki/wiki/wiki/wiki/ [...] /index.php' check that $wgserver does not contain any over-lapping path with the $wgScriptpath, $wgScript and $wgArticlePath. The following is an example of what should NOT be done: Because both of the first two variables end in "/wiki" the result will be that the 'Alias /index.php /filesystem/path/to/my/site/index.php' line in httpd.conf will instead redirect ANY index.php file on your whole site to the broken looping alias stated above. Ensure that the $wgServer does not contain any of the contents of the variables mentioned above.

Known working setup based on the above, presuming that you have renamed 'wiki' to 'w' on your server: /wiki

/var/www/w/LocalSettings.php
Note: The location of the web root can vary - it might not be /var/www

httpd.conf
Alias /wiki /var/www/w/index.php Alias /index.php /var/www/w/index.php Note: Windows tends to prefer quotes around paths for aliases, even if there are no spaces. If your web root is not /var/www THIS NEEDS TO BE CHANGED
 * 1) Put these lines AT THE BOTTOM and IN THIS ORDER

Ampersands and other encoded characters in titles
This problem shows up when you have page titles with symbols in (such as &, ?, #, + and /) that, despite being correctly encoded in the link are not being passed correctly from mod_rewrite to the script. This manifests in 404 page not found errors, because the title gets cut off at the special character. e.g. Clicking on a link "John & Maria's page" gets a 404, because MediaWiki is looking for a page names "John ".

If you are having problems with this, try transforming the reqested URL to the semi-friendly format of <tt>.../wiki/index.php/pagename</tt> rather than to the long format of <tt>...index.php?title=pagename</tt>. The reason for this is that using the long form means that articles can't have ampersands in their name because they would be treated as query string separators and would never reach the PHP runtime environment. The semi-friendly format is descriptive enough for apache to determine that the index.php script should handle the request. MediaWiki is prepared for this format and obtains the article title directly from the full request information in the <tt>$_SERVER</tt> hash.

RewriteRule ^(.*[^/])/?$ /index.php?title=$1 [QSA,L] becomes: RewriteRule ^(.*[^/])/?$ /index.php/$1 [QSA,L]

The cause of this is a long standing mod_rewrite bug.

There are discussions of other workarounds at: http://lists.wikimedia.org/pipermail/mediawiki-l/2005-June/005814.html http://fgiasson.com/blog/index.php/2006/07/19/hack_for_the_encoding_of_url_into_url_pr/