Recent Changes - Search:




RSS Feeds Logo

Edit Sidebar

Clean UR Ls


This recipe deals with how to get rid of that "pmwiki.php" part in the URLs that lead to a PmWiki site.


That is, PmWiki will be at URLs like http://some.doman/path/to/wiki/Group/Page instead of http://somedomain/path/to/wiki/pmwiki.php?n=Group.Page or http://somedomain/path/to/wiki/pmwiki.php/Group/Page.


 http://somedomain/path/to/wiki/pmwiki.php?n=Group.Page や、
 http://somedomain/path/to/wiki/pmwiki.php/Group/Page 形式ではなくて、

http://some.doman/path/to/wiki/Group/Page 形式のURLを吐くように設定する方法。


This page currently deals with Apache 1.3/2.0 in conjunction with mod_rewrite(approve sites).

This page won't help you if you are using a different WWW server (such as Internet Information Server, Xitami, or Zope). It also won't help you if somebody else is in control of the Apache installation and refuses to install or activate mod_rewrite for you, or has Apache configured in a way that your .htaccess(approve sites) files are ignored.

Technique 1: .htaccess and mod_rewrite

Use this technique if you cannot (or don't want to) modify your main Apache configuration files (httpd.conf et al.).

All changes are made in the PmWiki installation directory (i.e. the directory that contains pmwiki.php), which is supposed to be in /DocumentRoot/path/to/wiki, and has URL http://some.domain/path/to/wiki/.

config.php Edit:

To make PmWiki display the shorter URLs, you'll have to set

  $ScriptUrl = 'http://some.domain/path/to/wiki'

in config.php (no trailing slashes).

On its pages, PmWiki will normally generate query-style URLs of the form http://some.domain/path/to/wiki/pmwiki.php?n=Group.Page. To make it generate path-style URLs like http://some.domain/path/to/wiki/Group/Page, set

  $EnablePathInfo = 1;

wiki root edit:

First, create or change a file named index.php so that it reads:

  <?php include 'pmwiki.php';

This will make sure that URLs like


will automatically call pmwiki.php. (This should actually work with all servers.) This step isn't strictly necessary, but it's a safety net in case that a URL like the above makes it through the rewrite engine without being rewritten.

I prefer to include this line in .htaccess instead:
DirectoryIndex pmwiki.php
This gives you a clean url for the site root.
In this case you have to omit the first rewrite rule though.
If it doesn't work, change the <Directory> section in http.conf:
AllowOverride Indexes
I think the potential AllowOverride complexities make DirectoryIndex a less useful solution. Besides, the index.php trick always works, so why bother with .htaccess in the first place?
Joachim Durchholz? September 28, 2005, at 03:05 PM


After that, create or change a file named .htaccess so that it reads:

  Options +FollowSymLinks
  RewriteEngine on

  # Redirect browsers that use an empty URL
  # to the default URL.
  RewriteRule ^/?$ http://some.domain/path/to/wiki/dir/Main/HomePage [R=permanent,QSA,L]

  # Map URLs that start with anything but a lower-case letter to pmwiki.php.
  # The remaining URLs are left to the default map-to-filesystem routine of Apache.
  RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]
If you see "Options not allowed here" or "RewriteEngine not allowed here" change the <Directory> section in http.conf:
AllowOverride Indexes Options FileInfo
You may need to add a RewriteBase directive(approve sites) if you get a 404 error when accessing the clean URLs
RewriteBase /logical/path/to/wiki

You can leave out the comment lines that start with a hash mark #, but it's probably a good idea to leave them in anyway: if you or somebody else wants to modify the configuration later, the comments will help in understanding what the directives do.

The first two directives enable rewrite processing. (Yes, you need FollowSymLinks - the rationale is that if symlinks are not allowed, the far more powerful abilities of mod_rewrite shouldn't be allowed either.)

The first RewriteRule redirects http://some.domain/path/to/wiki/dir and http://some.domain/path/to/wiki/dir/ to the start page of the wiki. (Feel free to select a different group and page than Main/HomePage if you wish.) The final [R] option establishes the rewrite in a way that the user's browser is notified and can update the address bar.

The second RewriteRule takes the URL and inserts pmwiki.php/ at the right place. It does not apply to URLs that begin with a lowercase letter (because these are reserved for URLs that contain all sorts of auxiliary information: pub/skins, pub/css, favicon.ico, and last but not least pmwiki.php itself). It also avoids rewriting URLs that start with a slash, since sometimes the rewrite rule will be fed with absolute directory paths (which are guaranteed to start with a slash - on a Windows system, you should probably do something like RewriteRule ^([^\\a-z][^:\\]?.*) pmwiki.php/$1 to capture UNC names and names starting with a drive letter).

The second RewriteRule could also be written as

  RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]

This might be necessary if path-style URLs don't work (it seems to be possible to misconfigure Apache and/or PHP in this way). The QSA option is necessary to preserve ?action=edit and similar things - this tells mod_rewrite to add the ?n=$1 string to the URL instead of replacing everything after the first question mark.


If there is some problem with the rewrite rules, turn on rewrite logging (RewriteLog(approve sites) /path/to/rewrite.log) and set the rewrite log level to 9 (RewriteLogLevel 9) if you can. This will tell you in excruciating detail when and what mod_rewrite is doing, and give you hints where the problem actually is. Rewriting is an iterative process, and if you get an error message, it may be working on a URL that was already rewritten to something not even remotely similar to what you'd expect.

To switch on rewrite logging, you need access to httpd.conf. If you don't have that (that's quite the normal case), set up a test installation on your personal computer. For a Windows box, you can get a quite painless install from sites).

Note 1. This recipe will work even if you have a wiki-only site (i.e. if pmwiki.php is in the document root, and users are expected to use URLs like http://some.domain/Group/Page).

Note 2. To make PmWiki display the shorter URLs, you'll have to set

  $ScriptUrl = 'http://some.domain/path/to/wiki'

in config.php (no trailing slashes). To make PmWiki generate path-style URLs (i.e. .../Group/Page instead of ...?n=Group.Page in the pages that it outputs, set

  $EnablePathInfo = 1;

Joachim Durchholz? April 01, 2005, at 02:25 PM

Technique 2: "Alias"

Use the aliasing feature of Apache. Edit the httpd.conf file, and add a line like

 Alias /wiki "/var/www/html/pmwiki.php"

where you would of course specify the correct path to pmwiki.php. Then put

 $EnablePathInfo = 1;
 $PubDirUrl = " sites)";

in config.php.

adding the correct path to the "pub" directory with out the pmwiki.php. Alias messes up the links into the pub directory when pmWiki tries to auto sence that.

Note that this requires write access to the httpd.conf file (since Alias directives aren't allowed in directory or .htaccess context). Most webspace providers disallow this, since it's easy to kill Apache by providing invalid content in httpd.conf. -- JoachimDurchholz? 22 Mar 2005

Technique 3: Apache Configuration

Again, this requires write assess to httpd.conf.

  • Enable mod_rewrite LoadModule rewrite_module modules/
  • Add a Directory(approve sites) directive for your pmwiki directory (this is where your .htaccess file exists).
  • Specify AllowOverride(approve sites) Options, or Apache will not process options found in the .htaccess file.
  • Specify Options(approve sites) FollowSymLinks
  • Don't forget to restart Apache

Questions & Discussion

CleanUrls does not work on my pages... I'm not experienced enough in programming, so I don't get it to work. First, I have pmwiki.php renamed to index.php (and it works very well); then, I have installed pmwiki on my root-directory; when changing the lines in my .htaccess in the root directory, none of my scripts are working correctly, my server didn't allow anything. I had to upload the old .htaccess via ftp to get it all back to work. Is it a prob depending on my retail-hoster does not allow such kind of manipulation? How can I find out if the Apache's "mod_rewrite" capabilities are working?

  • Peter? December 28, 2004, at 01:36 AM
It's possible that your web server doesn't allow url rewriting (some don't). Is there a URL that I could look at -- maybe I can figure something out. --Pm?

Yes, see sites) , some new family-pages of mine. I have tried to get some information from my hoster, but they need time to answer...

  • Peter? December 28, 2004, at 03:34 PM
The URLs on your pages seem to be rather different from what they should be. For example, on I found$Group/Schnippsel?action=edit(approve sites) (note the dollar sign before "Group"). JoachimDurchholz?

I couldn't get the directions on step 2 to work on my commercial webhost that does give me access to .htaccess file, but not a full path to the folders I'm given. I got it working when I changed the .htaccess file in the root of the pmwiki installation to look like below - with no path to pmwiki at all and following all other directions.

     RewriteEngine on
     RewriteRule ^([A-Z].*) pmwiki.php?n=$1 [L,qsappend]
     RewriteRule ^$ pmwiki.php [L,qsappend]


You can easily discover the pathnames used on your webhost by putting up a simple php script that looks like
The very bottom of the huge mass of output should list all the relevant directories.

My webhoster also doesn't allow any .htaccess file changes. Is there a standard workaround to this problem? If the solution isn't all that complex and works in most cases, it might be a good idea to add it to the page. I could imagine many others are in the same situation as I am.

You're out of luck. Change the webhoster or live with the long URLs. -- JoachimDurchholz? 22 Mar 2005

This seems like a long shot, but is there a way to configure PmWiki to use the 'Main' namespace implicitly - but hide it from the urls?

You need a RedirectMatch that maps URLs with "Main" in them to the plain URLs (PmWiki will generate those URLs). You'll also need a RewriteRule that matches only those URLs that don't contain the group name and inserts a "Main/" at the appropriate place. (Results from RedirectMatch are shown in the address bar of the browser, results from RewriteRule aren't.) -- JoachimDurchholz? 22 Mar 2005

Jan 24, 2005

I tried to set this up on a local wiki. Our admin was setting up a certificate so that the wiki would be accessible via https. However it seems that when using 'Clean form' the links point back to HTTP server vs HTTPS. Any way to fix or address this? Thank you.

-- Gennady
Sure, just set the value of $ScriptUrl explicitly to use a relative uri (i.e., to omit the leading http://server part). --Pm?

Tried the above howto and it works fine. But uploading doesn't work anymore, I had to change the upload.php and change the action to ~/pmwiki.php -- UH

Just a Tip to easily define the directories

    $EnablePathInfo = 1;
    $BaseUrl = 'http://'.$_SERVER[HTTP_HOST];
    $ScriptUrl = $BaseUrl.'/~me/pmwiki';
    $PubDirUrl = $BaseUrl.'/~me/pmwiki/pub';
    $UploadUrlFmt = $BaseUrl.'/~me/pmwiki/uploads';

should work fine --Isidor?

Note: This does not work with Windows 2K. -Doug Parker
Is it that it doesn't work with Windows 2K, or that it doesn't work with IIS? Many people have Apache running under Windows, where this ought to work...? --Pm?

Note on localization - this does not seem to work with swedish characters, i.e. Å, Ä, Ö. Has something to do with http?

My guess is that this was a problem with an old version of the recipe where URLs using uppercase lessers in the A-Z range were taken to be wiki pages. The current version considers everything not in the a-z range to be a wiki page, so pages with umlauts and other "funny characters" in their name should work. Joachim Durchholz? April 01, 2005, at 02:25 PM

I really hate how pmwiki handles URLs. This helps, but is there a way to get rid of the annoying /Main/ part and possibly also avoid capitalization of every sentence in URLs as it looks incredibly stupid in any other language than English.

Propose an alternative url syntax. --Pm?
Use the ?n=Group/Page syntax. Joachim Durchholz? April 01, 2005, at 02:25 PM

I followed all the instructions and it didn't work... Finally I realized my .htaccess file was being ignored. When I checked my httpd.conf I found the following:

AllowOverride None

which completely disables .htaccess files. That is the default configuration on Fedora Core 1 Linux with Apache 2.0.50. Changing that line to:

AllowOverride All

and restarting httpd fixed the problem.

--PhilHollenback? 2005-3-21

You've jeopardized security. I strongly recommend you only do that in <directory> statements which cover the pmwiki installation dir.

Worked first time for me. However, now all the default PmWiki pages which I planned to leave there have links in the old format :b Any easy workaround? --Riccardo G. 2005-3-30

Shouldn't be any workaround needed -- PmWiki will still continue to recognize the old-format links. --Pm?

URL Rewriting under Apache 1.x on Win32 (the one from sites), I can't speak for the sites) version) doesn't work - see: sites)

Using Apache 2.0+ (as per the link above) is apparently the only solution for those stuck with Win32. To quote the last entry in the bugzilla issue above:

Whoops. Ok, this has simply got to be marked won't fix.
As I said 15 months ago - it is simply NOT possible to straighten this out in Apache 1.3/Win32. Nothing has changed, or will change, in that answer. If you don't like the behavior (certainly I don't :-) then upgrade to 2.0.

AllowOverride All is still required in the httpd.conf file to allow .htaccess files to work.


the problem is that Windoze Apache 1.3 converts all parts of a URL that appear to be a directory/file path to lower case before the URL is processed by the rewrite engine. this means that rewrite rules which depend on a leading capital letter will not work. in general, if the page URL ends with '.../Group/Page', interCaps will (sometimes?) be lost in the group name, and if it ends with '.../Group.Page they are lost on the page name as well. fwiw, --bang? June 04, 2005, at 09:01 AM

As at 2.0 b32 an extra command (and the index.php trick above) needs to be used to allow searching to work:

RewriteEngine on

RewriteCond %{QUERY_STRING} ^$
RewriteRule ^/?$ http://wiki.server/path/Main/HomePage [R=permanent,L]

RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]

Without this you will get a url like so:

With it you get a url like this:


Perhaps this ought to be placed in the instructions above - this seems to me a fairly important fix... Jon?

The same still applies in Apache 2.0.54. stormspotter?

For this method to work, Apache has to be configured to support rewriting. Add this to your httpd.conf:

LoadModule rewrite_module /path/to/your/apache2/modules/

And make sure, the pmwiki directory allows rewriting by adding the AllowOverride All statement mentioned above into that file.

On my machine, I run debian which puts the apache modules into /usr/lib/apache2/

Debian uses the following mechanism: /etc/apache2/ contains two directories with the names mods-available (all available modules) and mods-enabled. To enable an available module, simply symlink the corresponding file in mods-available into the mods-enabled directory: Debian's apache startup takes care of loading the module (You will still have to add the AllowOverride All directive though).

Orm Finnendahl?

On a site hosted with Apache 2, I'm having an annoying problem. The url rewriting works fine, except when I follow a link, there is an extra '/' in the url. For example, you're in the WikiSandbox and you want to go back to the main page, so you click the link and it will take you to sites) instead of sites).

I know it's fine to leave it like this, as it's working, but it doesn't look as 'pretty' as I'd like it to. Especially when I'm already using mod_rewrite to clean up the url.

Any suggestions for how I can fix this?


I forgot to mention, if you want to see the problem on the site I have under development right now, you can go to sites) . stormspotter?

 $ScriptUrl = '';  


 $ScriptUrl = '';


sigh... Looks like I overlooked the obvious again. Thanks, Anno. stormspotter?

I cant get this to work on my site. I got the path style URLs to work but it still puts index.php or pmwiki.php in the url. -- Austin ( sites) )




It took me a couple of days, but now it works ...

I was told to use a RewriteBase function in addition ...

my final .htaccess:

#my pmwiki.php is located at http://www.some.domain/~username/MyTry/pmwiki.php
#Options +FollowSymLinks   - was not supported - always generated error
RewriteEngine on
RewriteBase /~username/MyTry/
RewriteCond %{QUERY_STRING} ^$
#and the stuff mentioneed at the beginning
RewriteRule ^/?$ http://www.some.domain/~username/MyTry/Main [R=permanent,QSA,L]
RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]

Additionally it's don't forgrt to add to your config.php a couple of lines proposed by Isidor? :-)

$EnablePathInfo = 1;
$BaseUrl = 'http://www.some.domain';
$ScriptUrl = $BaseUrl.'/~username/MyTry';
$PubDirUrl = $BaseUrl.'/~username/MyTry';
$UploadUrlFmt = $BaseUrl.'/~username/MyTry/uploads';

otherwise you might find some links not working on your webpage (especially attachements - since the 'uploads' dir got translated wrong...)

Cheers! LecHo

My Solution:

Create .htaccess file in root directory of wiki that looks like so:

DirectoryIndex pmwiki.php
RewriteEngine on
RewriteCond %{QUERY_STRING} ^$
RewriteRule ^/?$ [R=permanent,QSA,L]
RewriteRule ^([^/a-z].*) /pmwiki.php?n=$1 [QSA,L]

I had to add an extra "/" in front of pmwiki.php


If you are using "?" style URLs, then you need to use:

RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]

If you are using "slash" style URLs ("$EnablePathInfo = 1;" in config.php) then this line needs to be:

RewriteRule ^([^/a-z].*) pmwiki.php/$1 [QSA,L]

Leastways, that's what I needed to do to make it work.


I'm pretty sure you can do this with IIS, you just need a whole different configuration (i.e. not .htaccess). I'm running Win2003 w/ IIS 6. I'll let ya'll know how things work out, but if anybody has suggestions, I'll be listening as I'm working. BTW, does anybody know how to do a masked redirect using IIS? That would essentially solve this problem, then all you have to do is use aliases.

-Michael Ansel

The following .htaccess works for 1and1 shared hosting (Apache 1.3.33, PHP 4.3.10):

Options +FollowSymLinks
RewriteEngine on

# RewriteBase is the directory where pmwiki.php lives
RewriteBase /stw

# Redirect browsers that use an empty URL to Main.HomePage
RewriteRule ^/?$  /stw/Main/HomePage [R=permanent,QSA,L]

# Map URLs that start with anything but a lower-case letter to pmwiki.php.
# The remaining URLs are left to the default map-to-filesystem routine of Apache.
RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L] 


I too, found this recipe to be cumbersome. So here is my solution step by step.

Let's assume:

  1. DocumentRoot is /www
  2. PmWiki installed at /www/pmwiki
  3. Upload directory at /www/pmwiki/uP

Let's say that you would like your URLs to look like:


My /www/.htaccess file is:

Options -Indexes
ErrorDocument 403 /noindex.html
RewriteEngine On
RewriteRule ^/?$ [R=permanent,QSA,L]
RewriteRule ^wiki$ [R=permanent,QSA,L]
RewriteRule ^wiki/uP/([^/a-z].*) /pmwiki/uP/$1 [QSA,L]
RewriteRule ^wiki/([^/a-z].*) /pmwiki/pmwiki.php?n=$1 [QSA,L]

Now, in my /www/pmwiki/local/config.php file:

$ScriptUrl = '';
$PubDirUrl = '';
$EnablePathInfo = 1;
$EnableUpload = 1;
$UploadDir = 'uP';

I also have:

<?php include 'pmwiki/pmwiki.php'; ?>

in my /www/index.php, but maybe that's not required (?).


Categories: Administration

Edit - History - Print - Recent Changes - Search
Page last modified on October 09, 2005, at 11:38 AM