TextBook

From Textbook

These instructions are specifically for version 1.0. If you're working on any earlier version of Textpattern (e.g., rc1) and you want clean URLs but are having trouble, then use the information available in the Textpattern Forum (it's spread all over, but it's there); we are only concerned with v 1.0 here.

You do not have to use clean URLs, they are just better for your site visitors if you do because they provide them with more orientation cues while browsing (navigating) your site. If you do not care about site usability then you can go with Messy URLs, simply select the "?=messy" option in the Permanent Link Mode drop-down box in the Preferences Subtab panel and forget about the rest of these instructions.

The Process

Step 1: Ensure You Have mod_rewrite Capabilities

Before you go any further, you should make sure you have Mod_Rewrite capabilities; if you don't, you will not be able to use clean URLs and will have to settle for messy URLs. To check to see if you have Mod_Rewrite abilities, do the following:

1. Create a new file with a .php extension, name it anything you like (but something easy to remember, because it's just temporary).
2. Add the following to the file (and nothing else)...

   <?php phpinfo(); ?>

3. Upload the file to your Web root, and run it in your browser (type the URL to the file in the browser address bar and hit Enter).

In the resulting file, you want to look in the "Apache" section, then "Loaded Modules", and then for something indicating Mod_Rewrite. If you have Mod_Rewrite, then you can proceed beyond step 2. If not, then finish step 2 as follows and call it good with your URLs.

Step 2: Getting Ready in "Messy" Mode

It is assumed at this point that you have already set your site preferences as you want them to be in the Preferences Subtab panel, and you have probably even tried fixing any diagnostics issues in the Diagnostics Subtab panel.

However, what you should do now is go back and make sure you have selected the "?=messy" option in the Permanent Link Mode section of the Preferences Subtab panel. (This enables you to establish some site structure and troubleshoot diagnostics easier, which are the next things to take care of.)

If you have not set your preferences and handled your diagnostics, make sure you do so before continuing.

Step 3: Creating Some Content Structure to Work With

If you do not already have some structure to your site (Sections, Pages, Articles, etc.) with which to focus on clean URLs, then you will need to detour from these instructions for a while to get your site structure/content in place; without it, you will not have context to which you can see if your clean URLs are working or not. You do not need to have your entire site finished (though if you do, that's fine), but you should have at least a couple of Sections setup with one or more Articles associated with each section.

If you do have some structure and content to your site, then what you need to think about now is how you want your clean URLs to look, and again we refer you to the Permanent Link Mode options in the Preferences Subtab panel where you set this.

Step 4: Addressing Your .htaccess File mod_rewrite Rules

With luck, clean URLs will just work with the .htaccess file distributed with Textpattern.

One situation in which it may need to be tweaked is if you have not yet transferred your DNS entry to point to the new server, so you are accessing your site with a URL such as http://169.254.23.74/~mysite

In this case you would add the following RewriteBase rule to the .htaccess file:

RewriteBase /~mysite

Note that there should be no trailing slash on the directory name. This line goes immediately after RewriteEngine On.

Don't forget to remove it before you get the DNS entry updated.

If Nothing Works

If you don't get Clean URLs to work the first time around, double-check everything you can think of. If that still does not work, then remember this...

"Most likely your hosting company has done something to disable or limit .htaccess. We...[TxP Developers]...have done our best to make clean URLs work on as many hosts as possible; unfortunately, there are many ways to configure Apache such that .htaccess needs to be specially customized for that particular server, or perhaps won"™t work at all." (from zem, right here.)

In short, there is no guarantee that clean URLs are going to work.