How to enable shorter URLs in TWiki

This supplemental document describes how to enable shorter URLs on your TWiki site. To do this, all you will need is access to your web server configuration file and direct access to LocalSite.cfg.

When implemented, this will change your view URLs from:

www.example.com/bin/view/Main/WebHome   to   www.example.com/Main/WebHome.

If you're ready to tweak TWiki.pm a bit, you can shorten links even more by dropping the default web name out of them, whether it's "Main" or not:

wiki.example.com/bin/view/DefaultWeb/NiceTopic   to   wiki.example.com/NiceTopic.

All the hyperlinks on your twiki site which use the view script will also be displayed in this way.

It will not change any other URLs (i.e edit, attach, oops, rdiff...). So the following

www.example.com/bin/edit/Main/WebHome will stay the same.

This might be seen as a limitation, however the main reason you would want this is so you can tell someone else how to get at a particular topic, without having to explain the /bin/view bit. Also, this method is only three lines long, so you can't expect much more.

If you have to type /bin/edit and other actions too often, you can shorten them, too. For example from /bin/edit/ to /e/.

Changes to Apache's httpd.conf

Option 1: Use overlapping aliases

This is the easiest solution with the least server impact but it does require a little twist in setting up TWiki.

Normally, you would have these 2 lines (and directory settings) in your Apache configuration file:

ScriptAlias /URL/to/twiki/bin "/path/to/server/twiki-root/bin"
Alias /URL/to/twiki "/path/to/server/twiki-root"

/URL/to/twiki could be an empty string, for when you want to serve just TWiki on your (virtual) web server. The configuration would then be

ScriptAlias /bin "/path/to/server/twiki-root/bin"
Alias / "/path/to/server/twiki-root/"

The trick is to assume any URL under /URL/to/twiki is a TWiki view URL, except for URLs under /URL/to/twiki/bin and /URL/to/twiki/pub. To do that, we first define aliases for bin and pub, and then specify that everything else is calling the view script:

ScriptAlias /URL/to/twiki/bin "/path/to/server/twiki-root/bin"
Alias /URL/to/twiki/pub "/path/to/server/twiki-root/pub"
Alias /URL/to/twiki "/path/to/server/twiki-root/bin/view"

In case of a dedicated TWiki web server, you'd write

ScriptAlias /bin "/path/to/server/twiki-root/bin"
Alias /pub "/path/to/server/twiki-root/pub"
Alias / "/path/to/server/twiki-root/bin/view/"

As you can see, it has a slightly counter-intuitive twist where the "regular" URLs are actually shortcuts for URLs under bin.

This works without having to enable any special features in Apache, and has the added bonus of keeping any other TWiki subdirectories out of the visible files on the web server.

Warning: There is a problem with this method if the prefix to your twiki installation is the same as the name of a web. For example, you can't use http://server/twiki/ as the short URL to your TWiki installation. It will seem to work, but http://server/twiki/TWiki/WebHome and any other topic under TWiki won't work. The reason for this is rather technical: in TWiki.pm, the PATH_INFO variable is stripped of the script name (in this case "/twiki") using a case-insensitive search.

• Moral: Don't use a prefix that is the same as the name of one of your webs. A "dedicated" setup is fine though.

Option 2: Use the URL rewrite engine

First, edit your httpd file and insert the following two lines somewhere:

RewriteEngine on

RewriteRule ^/([A-Z].*) /var/www/twiki/bin/view/$1 [L] - Change /var/www/twiki/bin/view to the path to your view script

This will check the incoming URL to see if it starts with an uppercase letter (i.e. Main/WebHome). If it does, it will be rewritten to the view script (so Main/WebHome becomes /var/www/twiki/bin/view/Main/WebHome). If it does not start with an uppercase letter (i.e. bin/edit/Main/WebHome), nothing will be changed. Therefore, the original long view URLs (www.example.com/bin/view/Main/WebHome) will still work as expected, not breaking any bookmarks.

Changes to Lighttpd's lighttpd.conf

This example works for standard shortening, where links contain both web and topic names, like http://d9hbak1pgjkmem4kvumj8.roads-uae.org/WebName/TopicName:

$HTTP["host"] == "wiki.cenkes.org" {
   server.document-root = "/usr/local/www/twiki"
   url.rewrite-once = (
      "^/e/([A-Z].*)" => "/bin/edit/$1",
      "^/([A-Z].*)" => "/bin/view/$1",
      "^/pub/TWiki/(.*)" => "/pub/TWiki/$1",
      "^/pub/(.*?)/([^/]+)$" => "/bin/viewfile/$1?filename=$2" )
   url.rewrite-repeat = ( "^/?(index.*)?$" => "/Main" )
   $HTTP["url"] =~ "^/bin" { cgi.assign = ( "" => "" ) }
}

This example works for extra shortening, where links to topics within a particular "default" web do not contain web name, like http://d9hbak1pgjkmem4kvumj8.roads-uae.org/TopicName, but links to topics in other webs contain both web and topic names:

$HTTP["host"] == "wiki.cenkes.org" {
   server.document-root = "/usr/local/www/twiki"
   url.rewrite-once = (
      "^/e/((WebName|Main|Sandbox|TWiki).*)" => "/bin/edit/$1",
      "^/((WebName|Main|Sandbox|TWiki).*)" => "/bin/view/$1",
      "^/e/([A-Z].*)" => "/bin/edit/Cenkes/$1",
      "^/([A-Z].*)" => "/bin/view/Cenkes/$1",
      "^/pub/TWiki/(.*)" => "/pub/TWiki/$1",
      "^/pub/(.*?)/([^/]+)$" => "/bin/viewfile/$1?filename=$2" )
   url.rewrite-repeat = ( "^/?(index.*)?$" => "/Main" )
   $HTTP["url"] =~ "^/bin" { cgi.assign = ( "" => "" ) }
}

Changes to LocalSite.cfg

Next (for both options in the previous section), edit your LocalSite.cfg and add:

$TWiki::cfg{ScriptUrlPaths}{view} = '';

Note the plural Paths, it is a different hash key than ScriptUrlPath. This cannot be done through configure, so you will need to do it manually. If you want to shorten other actions, you can do it in a similar fashion:

$TWiki::cfg{ScriptUrlPaths}{edit} = '/e';

Don't forget to tweak your web server configuration accordingly if you do this. Examples available for Lighttpd only, see above.

Changes to lib/TWiki.pm - for extra shortening

This pseudo-patch should give the idea:

-       $url .= urlEncode( '/'.$web.'/'.$topic );
+       if($web eq "SomeDefaultWeb"){
+               $url .= urlEncode( '/'.$topic );
+       }else{
+               $url .= urlEncode( '/'.$web.'/'.$topic );
+       }

Don't forget to tweak your web server configuration accordingly if you do this. Examples available for Lighttpd only, see above.

Finally...

Restart your web server, and then you're done. Shorter URLs for all!

Accessing rewritten URLs

TWikiRelease04x00x00 also introduces an extension to the SCRIPTURL TWiki Variable to support rewriting rules for scripts for URLs in templates and in topics. See TWikiVariables in your local TWiki documentation for more information.

Advanced: redirecting long URLs to shorter ones

Even if you've configured everything correctly, there's still a chance that the long URLs containing /bin/view/ will be exposed on the Internet and generate some hits. You may want to generate 30x redirects for them, so that caches and search engines will be less confused.

It is not that simple, since in a nutshell here's what you'll be trying to tell your web-server:

• when someone accesses http://wiki/Main/Page, give them (rewrite to) http://wiki/bin/view/Main/Page
• when someone accesses http://wiki/bin/view/Main/Page, redirect them to http://wiki/Main/Page

Depending on your web-server, you can get into an endless loop of rewrites and redirects. But there's a simple solution:

• access the twiki file system and create a symlink (or a copy) from bin/view to bin/X-view:

  ln -s view /usr/local/www/twiki/bin/X-view

• rewrite URLs like http://wiki/Main/Page to http://wiki/bin/X-view/Main/Page
• redirect URLs like http://wiki/bin/view/Main/Page to http://wiki/Main/Page

This way you'll avoid loops. Note that only view action is shortened. Other actions are mostly interactive and don't raise concerns about caching and search indexing.

Lighttpd example

This configuration example works with extra shortening, with default web name Cenkes dropped from links. E.g. both http://wiki/bin/view/Cenkes/Page and http://wiki/Cenkes/Page will always be shortened (redirected) to http://wiki/Page.

url.rewrite-once = (
   "^/((Main|Sandbox|TWiki).*)" => "/bin/X-view/$1",
   "^/e/((Cenkes|Main|Sandbox|TWiki).*)" => "/bin/edit/$1",
   "^/e/([A-Z].*)" => "/bin/edit/Cenkes/$1",
   "^/([A-Z][^/]*(\?.*)?)$" => "/bin/X-view/Cenkes/$1",
   "^/pub/TWiki/(.*)" => "/pub/TWiki/$1",
   "^/pub/(.*?)/([^/]+)$" => "/bin/viewfile/$1?filename=$2" )
url.redirect = (
   "^/Cenkes/(.*)" => "http://d9hbak1pggpv9apnuj8f6wr.roads-uae.org/$1",
   "^/bin/view/(Cenkes/)?(.*)" => "http://d9hbak1pggpv9apnuj8f6wr.roads-uae.org/$2",)

See also...

ShorterURLs, ShorterCaseInsensitiveURLs, ShorteningUrls.

FAQ

Is this a security risk to shorten the url from /wiki/bin/view/TWiki/WebHome to just /wiki/TWiki/WebHome ?

There is no security risk.

Script URL and pub URL

So, to clarify though, the script URL and pub URL should still be /twiki/bin and /twiki/pub respectively (on the configure screen)?

Yes, everything in configure should stay the same, although you do need to set $TWiki::cfg{ScriptUrlPaths}{view} = ''; in lib/LocalSite.cfg

-- Contributors: CrawfordCurrie, AndrewRJones, WoutMertens

---

Comments & Questions about this Supplemental Document Topic

See topic history for excised comments (removed for clarity)

We ran into a little issue getting this set up, so figured it might be worth sharing. It turns out that the RewriteRule for us had to be relative to the document root:

RewriteRule ^/([A-Z].*) /twiki/bin/view.pl/$1 [PT] [L]

We had to add the [PT] also so it could deal with the Aliases. We also found that if we use the absolute path in the RewriteRule to the twiki install, we needed to add a

<files *> SetHandler cgi-script </files>

entry to the /twiki/bin <Directory> element.

HTH!

-- StephanieDalPra - 28 Sep 2006

Found a little limitation with this. If someone was to type the following in the jump box:

/Main/WebHome

Lots of things break on the page, as listed below:

• Printable link
• Previous revision links (i.e. r17, r16...)
• Jump box
• Search box
• Internal links (i.e. [[TWikiUsers][Users]])

The amount of people that type /Main/WebHome in the search box is probably very small (I only did it when copying and pasting from my Apache error log), so its probably not much of an issue.

-- AndrewRJones - 09 Oct 2006

If you set the view url to '' as described above, and you're not running 4.0.5 or later, that will not work. In TWiki.pm, the function getScriptUrl has a line saying

unless( $url ) {

That line should be changed to

unless( defined $url ) {

The first form will see an empty string as an undefined string, and the view urls will then be handled like the rest.

Or you could upgrade

-- WoutMertens - 23 Nov 2006

In the 4.1.2 distribution, the base HREF will still have the /view/ prefix, it is inserted by page.pattern.tmpl or twiki.tmpl. This may or may not lead to errors with page-internal links, depending on your precise Rewrite setup. See Bugs:Item3968 for more information

-- JoachimSchrod - 27 Apr 2007

There is an easier way, i.e. no rewriterules, this is what i have

DocumentRoot /home/musmo/0405-live
Alias /pub "/home/musmo/0405-live/pub/"
ScriptAlias / "/home/musmo/0405-live/bin/"

In configure (or lib/LocalSite.cfg) you must have,

$TWiki::cfg{ScriptUrlPath} = '/';

Works very well for me. Basically there's no cgi-bin or bin in the url anymore.

-- KwangErnLiew - 27 Apr 2007

But you still have URLs that look like /view/Web/TopicName, since you only discard the prefix (/twiki/bin or whatsoever). This topic is about discarding the /view prefix as well.

-- JoachimSchrod - 27 Apr 2007

I have partial success with this: the links http://wiki/TWiki/WebHome now work as expected. However, on the topics themselves all autolinks still refer to http://wiki/bin/view/TWiki/SomeTopic

I used the RewriteRule by StephanieDalPra and the singular version on the LocalSite.cfg ScriptUrlPath entry. Does anyone have and idea what's going wrong?

-- JosMaccabiani - 14 Jun 2007

I think an easier way is:

vim ../.htaccess

RewriteEngine on
RewriteRule ^([A-Z].*) /twiki/bin/view/$1 [PT] [L]

vim lib/LocalSite.cfg

$TWiki::cfg{ScriptUrlPaths}{view} = '';

-- HectorPerezArenas - 26 Sep 2007

Using Twiki 4.1.2, I still got 'view' in generated URLs, even though I followed HectorPerezArenas advice (listed as option 2). I even followed JoachimSchrod's advice in his bug report, and did a find / replace on all the template files like so:

sudo sed -i.bak 's:%SCRIPTURL%/%SCRIPTNAME%/:%SCRIPTURL{%SCRIPTNAME%}%:g' *

It seems the only way I could fix the issue to remove view from auto-generated urls was to hack TWiki.pm to add the following within the getScriptUrl method (after the first if statement below):

    if( defined $TWiki::cfg{ScriptUrlPaths} && $script ) {
        $url = $TWiki::cfg{ScriptUrlPaths}{$script};
    }
    if( $script =~ 'view') {
        $url = '';
    }

Could anyone advise a more sensible way than this little hack - why is if (defined $Twiki::cfg{ScriptUrlPaths}{$script} && $script ) not matching what is defined in the config file?

-- JustinClarke - 17 Oct 2007

For a dedicated twiki setup, I found that adding

Alias /twiki "/path/to/server/twiki-root/"

..which is essentially stating the obvious, to be really necessary before the final / alias, to catch those stray templates/scripts which insist on still using /twiki URLs, e.g. the TWikiRegistration page.

-- SandipBhattacharya - 17 Dec 2007

Is there a way to simply map (rewrite) intranet.mydomain.com to http://4jmn299xgj4ewk1dwvrj8.roads-uae.org/twiki/bin/view/Intranet/WebHome?

-- MikePrest - 2010-02-18

Yes, see http://75mmg6t6gjgr3exehkae4.roads-uae.org/docs/2.2/mod/mod_rewrite.html

-- PeterThoeny - 2010-02-19

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.