Using personalised URLs

After installation, pages generated with SPIP use relative addresses of the form spip.php?article765, which results in URLS like http://www.spip.net/spip.php?article765.

There is a possibility to have addresses more to your taste if you choose — for example article123.html or Title-of-the-article.html, and SPIP helps you with a portion of this task.

This functionality requires an understanding of the difference between the two types of URL:

-  the apparent URL of a page, being what you typed into or what is displayed in the address bar of your navigator. For example, http://www.spip.net/fr_article3588.html. These are the URLs that people often want to make "prettier" or "more meaningful" ;

-  the real URL of the page, being the URL that is "seen" by SPIP whenever the page is calculated on the server. For example, http://www.spip.net/spip.php?article3588 ; is typical, and this URL can also be typed directly into the navigator (you can confirm this).

Selecting the form of the apparent URLs

In the ecrire/mes_options.php file [1] (create this file if there isn’t one already), you can declare a PHP variable containing the type of URLs to use. In the absence of such an explicit statement, SPIP will use :

$type_urls = "page";

The $type_urls variable determines the PHP filename that is called when generating the URLs. With the default declaration above, the PHP filename called is the first urls/page.php found on the SPIP_PATH.

SPIP also offers the other potential PHP filenames, being urls/standard.php, urls/html.php, urls/propres.php, urls/propres-qs.php and urls/propres2.php in the ecrire/ directory

-  The urls/html.php file allows for the use of addresses like ("article123.html"). You can decide to use these "html" URLs by changing your ecrire/mes_options.php file to include this line :
$type_urls = "html";

-  The urls/propres.php file allows for the use of addresses like («Title-of-the-article»). For this, you would need :
$type_urls = "propres";

-  The urls/propres2.php file is a variation of the previous form, and results in addresses like ("Titre-of-the-article.html"). For this, you would need :
$type_urls = "propres2";

-  The urls/propres-qs.php file is another similar variation which results in addresses like («./?Title-of-the-article»). For this, you would need :
$type_urls = "propres-qs";. This one is useful if your hosting server does not allow you to use the Apache URL rewriting module (cf. mod_rewrite)

-  Lastly, the urls/standard.php file allows for the nostalgically-inclined to generate addresses that previous versions of SPIP created like («article.php3?id_article=3588»). For this, you would need :
$type_urls = "standard";

If you would rather use your own addresses (for which you need to know how to program in PHP), it is highly recommended to use one of these files as a base and to copy it as the filename you wish to use : urls/XXX.php. For example, it is very easy to modify the _generer_url_propre() function in urls/propres.php to get some very interesting variations; if you do so, we’d thank you to share them through the SPIP Contrib’ site.

Programming the translation of apparent addresses into real addresses

So that the address article123.html actually calls the PHP spip.php file with id_article=123 as a parameter, it is necessary to configure the Web server that is hosting your site, be that with the .htaccess file (which is not always possible), or by editing the the central server configuration file if you have access to it. This technique uses, on Apache servers (the most common), what are known as Rewrite Rules : rules for rewriting Web addresses.

Knowing how to write these rules is not a simple matter for non-programmers, and we can’t give you solutions guaranteed to work because it depends a lot on your configuration : this component is entirely in your own hands and responsibility (or that of your host).

Nevertheless, since SPIP 1.8, 1.8.1 is supplied with an htaccess.txt file as an example, which works with most server hosts for the types of URL referred to above («standard», «html», «propres» and «propres2»). To activate it, it is necessary to recopy it to the site root directory, renaming it .htaccess. It is highly advised to open the file first to verify certain items of configuration.

You should then test the validity of the new address, by calling the "View on line" page of an article, an author, a news item, a section, etc.

Generating apparent URLs in the SPIP pages

In order to display the URLs according to the schema you have chosen, your templates should use the following tags: #URL_ARTICLE, #URL_RUBRIQUE, #URL_BREVE, etc.

Transitioning from one type of URL to another

Since SPIP 1.8, 1.8.1, everything has been prepared so that transitioning from one type of address to another can be done in complete confidence: install the htaccess.txt file, and you can then freely switch from "standard" addresses to "propres2" or "html" addresses, and vice versa, without provoking 404 errors for site visitors (of for search engines) that have memorised, indexed or bookmarked the presvious addresses.

As a last mention to make transitioning easier, if you select propres or propres2 URLs, visiting pages that carry the previous type of address (standard or html) are automatically redirected to the new addresses.