View source for Tidying Up Your MediaWiki URLs: A Guide to Hiding "index.php"

<span id="tidying-up-your-mediawiki-urls-a-guide-to-hiding-index.php"></span>
== Tidying Up Your MediaWiki URLs: A Guide to Hiding “index.php” ==

A cleaner, more user-friendly URL structure for your MediaWiki installation is easily achievable by hiding the “/index.php” portion of your document addresses. This process, often referred to as creating “short URLs,” not only enhances the aesthetics of your links but can also improve search engine optimization. This guide will walk you through the necessary steps to achieve this for the popular web servers, Apache and Nginx.

The core of this process involves two key modifications: first, adjusting your MediaWiki’s <code>LocalSettings.php</code> file to generate the desired URL format, and second, configuring your web server to correctly interpret these new URLs and route them to the appropriate MediaWiki script.

<span id="step-1-modifying-localsettings.php"></span>
=== Step 1: Modifying <code>LocalSettings.php</code> ===

The first step is to inform MediaWiki about your new URL structure. This is done by adding or modifying a few lines in your <code>LocalSettings.php</code> file, which is located in the root directory of your MediaWiki installation.

Open your <code>LocalSettings.php</code> file and add the following line:


<syntaxhighlight lang="php">$wgArticlePath = "/wiki/$1";</syntaxhighlight>
This line tells MediaWiki to format the URLs for your articles as <code>https://yourdomain.com/wiki/Article_Name</code>. You can replace <code>/wiki</code> with any other path you prefer, but it is a widely used and recommended convention.

It is also good practice to ensure the following setting is present, which is the default in modern MediaWiki versions:


<syntaxhighlight lang="php">$wgUsePathInfo = true;</syntaxhighlight>
This setting enables the use of “path info” in URLs, which is essential for the short URL functionality to work correctly.

<span id="step-2-configuring-your-web-server"></span>
=== Step 2: Configuring Your Web Server ===

After updating <code>LocalSettings.php</code>, you need to configure your web server to handle the new “pretty” URLs. The server needs to understand that a request for <code>/wiki/Article_Name</code> should actually be processed by the <code>index.php</code> script.

<span id="for-apache-users"></span>
==== For Apache Users ====

If you are using the Apache web server, the most common way to implement URL rewriting is by using a <code>.htaccess</code> file.

<ol style="list-style-type: decimal;">
<li><p>'''Enable <code>mod_rewrite</code>:''' Ensure that the <code>mod_rewrite</code> module is enabled in your Apache configuration. You can usually do this by running <code>sudo a2enmod rewrite</code> on Debian-based systems or by uncommenting the corresponding line in your <code>httpd.conf</code> file.</p></li>
<li><p>'''Create or edit your <code>.htaccess</code> file:''' In the root directory of your MediaWiki installation (the same directory as <code>LocalSettings.php</code>), create or edit the <code>.htaccess</code> file and add the following lines:</p>

<syntaxhighlight lang="apache">RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^/?wiki/(.*)$ /index.php?title=$1 [L,QSA]</syntaxhighlight>
<p>This configuration does the following:</p>
<ul>
<li><code>RewriteEngine On</code>: Enables the rewriting engine.</li>
<li><code>RewriteCond %{REQUEST_FILENAME} !-f</code> and <code>RewriteCond %{REQUEST_FILENAME} !-d</code>: These conditions prevent the rewrite rule from being applied to existing files or directories. This is important to ensure that direct requests to files like images or CSS are not rewritten.</li>
<li><code>RewriteRule ^/?wiki/(.*)$ /index.php?title=$1 [L,QSA]</code>: This is the main rule. It captures the article title from the URL and passes it as a <code>title</code> parameter to <code>index.php</code>. The <code>[L]</code> flag tells Apache to stop processing further rules, and <code>[QSA]</code> appends any existing query string to the rewritten URL.</li></ul>
</li></ol>

'''Important Note on Directory Structure:''' It is highly recommended that your MediaWiki installation itself is not in a directory named <code>/wiki</code>. A common practice is to install MediaWiki in a directory like <code>/w</code> and then use <code>/wiki</code> as the virtual path for your articles. This prevents potential conflicts between the physical directory and the virtual path.

<span id="for-nginx-users"></span>
==== For Nginx Users ====

For those using the Nginx web server, you will need to edit your site’s configuration file, which is typically located in <code>/etc/nginx/sites-available/</code>.

Within the <code>server</code> block of your site’s configuration, add the following <code>location</code> block:


<syntaxhighlight lang="nginx">location /wiki/ {
    rewrite ^/wiki/(.*)$ /index.php?title=$1;
}

location / {
    try_files $uri $uri/ @rewrite;
}

location @rewrite {
    rewrite ^/(.*)$ /index.php?title=$1;
}</syntaxhighlight>
This Nginx configuration achieves the same outcome as the Apache <code>.htaccess</code> rules. It defines a specific location block for your <code>/wiki/</code> path and rewrites the URL to be handled by <code>index.php</code>. The additional <code>location</code> blocks ensure that other requests are handled correctly.

After saving the changes to your Nginx configuration, you will need to restart the Nginx service for the changes to take effect. You can usually do this with the command <code>sudo systemctl restart nginx</code>.

<span id="troubleshooting-common-issues"></span>
=== Troubleshooting Common Issues ===

If you encounter problems after implementing these changes, here are a few common issues and their solutions:

* '''404 Not Found Errors:''' If you are seeing “404 Not Found” errors for your wiki pages, it is likely that the web server rewrite rules are not being processed correctly.
** '''Apache:''' Double-check that <code>mod_rewrite</code> is enabled and that your <code>.htaccess</code> file is in the correct directory and has the correct permissions to be read by the web server. Also, ensure that your main Apache configuration allows for overrides from <code>.htaccess</code> files (the <code>AllowOverride</code> directive should be set to <code>All</code> for your web root).
** '''Nginx:''' Verify that you have reloaded or restarted the Nginx service after modifying the configuration. Check the Nginx error logs for any syntax errors in your configuration file.
* '''Broken Links and Missing Styles:''' If the page loads but without any styling or images, it could be that the rewrite rules are incorrectly redirecting requests for these assets. The <code>RewriteCond</code> directives in the Apache configuration and the <code>try_files</code> directive in the Nginx configuration are designed to prevent this. Ensure they are correctly implemented.
* '''Redirect Loops:''' If you find yourself in a redirect loop, carefully review your <code>LocalSettings.php</code> and your web server configuration for any conflicting rules or incorrect paths.

By following these steps, you can successfully remove <code>/index.php</code> from your MediaWiki URLs, resulting in a cleaner and more professional-looking wiki. For more advanced configurations or if you encounter persistent issues, the official MediaWiki documentation on “Short URLs” is an excellent and comprehensive resource.