WordPress

Using Permalinks

Table of Contents

1 Permalink Types

1.1 Default ("Ugly")
1.2 mod_rewrite ("Pretty Permalinks")
1.3 PATHINFO ("Almost Pretty")

2 Structure Tags

3 Where's my .htaccess file?

4 Creating Rewrite Rules (.htaccess)

4.1 Using Permalinks Without mod_rewrite
4.2 Fixing Permalink Problems

4.2.1 Fixing (.htaccess) Generation Issues

4.3 Permalinks, .htaccess, and MS Frontpage

4.3.1 Quick Fixes, Frontpage or Permalinks
4.3.2 Using Frontpage AND Permalinks Together
4.3.3 A Final Note
4.3.4 Long Permalinks
4.3.5 Fixing Other Issues
4.3.6 More Help

5 Tips and Tricks

5.1 Having your posts end in .html

6 External Resources

Permalinks are the permanent URLs to your individual weblog posts, as well as categories and other lists of weblog postings. A permalink is what another weblogger will use to refer to your article (or section), or how you might send a link to your story in an e-mail message. Especially when they are used to link to individual postings, once a story is posted, the URL to it should be permanent, and never change. Hence the "perma" in the name.

Permalink Types

There are three basic types of WordPress permalinks:

Default ("Ugly")

The default looks like http://example.com/?p=N Where N is a number. This is the default for new WordPress installations because it works on all server environments. It is, however, not desired by many people, because it doesn't look as nice as some of the other options.

mod_rewrite ("Pretty Permalinks")

These are the holy grail of permalinks. There are many different formats, but the most common, and most versatile looks like http://example.com/yyyy/mm/dd/post-name/ Some people also eliminate some or all of the date elements (day, month, year) to have a shorter permalink format. mod_rewrite permalinks require Apache's mod_rewrite module, which means that people running other servers cannot use them. See Pretty Permalinks for more info.

PATHINFO ("Almost Pretty")

PATHINFO permalinks look very much like mod_rewrite permalinks but for one exception: they have /index.php inserted before them. Like so: http://example.com/index.php/yyyy/mm/dd/post-name/ Otherwise, they are the same as the "pretty" mod_rewrite permalinks, and are similarly flexible. Anything that mod_rewrite permalinks can do, PATHINFO permalinks can do, with the help of that /index.php part.

Structure Tags

You can use these tags to customize your "Pretty" or "Almost Pretty" permalinks.

%year%
The year of the post, four digits, for example 2004
%monthnum%
Month of the year, for example 05
%day%
Day of the month, for example 28
%hour%
Hour of the day, for example 15
%minute%
Minute of the hour, for example 43
%second%
Second of the minute, for example 33
%postname%
A sanitized version of the title of the post. So “This Is A Great Post!” becomes “this-is-a-great-post” in the URI (see note below)
%post_id%
The unique ID # of the post, for example 423
%category%
A sanitized version of the category name. Nested sub-categories appear as nested directories in the URI.
%author%
A sanitized version of the author name.

These types of permalinks work on most systems without any problems, but there are still some conditions where problems occur.

Note on using only %postname%
If you use postname as the only element in your permalinks to create a structure such as myblog.com/post-title, the rewrite rules may make it impossible to access pages such as your stylesheet (which has a similar format) or the wp-admin folder. It's best to include some numeric data (e.g. the post ID or date) in the permalink to prevent this from happening. Additionally, WordPress v1.2.x requires the use of a date structure in order for some features, such as the calendar, to function properly. /%year%/%monthnum%/%day%/%postname%/ is always a good start.
Note on using %category%
%category% does not work correctly with some implementations of mod_rewrite in Apache versions prior to 2. If you are using Apache 1 and experience problems with using %category, either do not use %category% in your permalink structure, or refer to Schlueterica's plugin (http://isaacschlueter.com/plugins/i-made/lucky-13-rewrite/).
Note on using %category% with multiple categories on a post
Where you assign multiple categories to a post, only 1 can show up in the permalink. This will be the lowest numbered category (see Manage Categories). The post will still be accessible through all the categories as normal.
Properly terminating permalinks
It's important to guarantee permalinks lead to individual posts within your custom URI, so make sure to end a virtual site structure with either %post_id% or %postname%

/%year%/%monthnum%/%day%/%postname%/

Where's my .htaccess file?

The .htaccess file should be in the directory indicated by your "Blog address (URI)" setting on your General Options page. Since the name of the file begins with a ".", the file may not be visible through an FTP client unless you change the preferences of the FTP tool to show all files, including the hidden files.

If you do not already have a .htaccess file, create one. If you have shell, or ssh access to the server, a simple touch .htaccess will create the file. If you are using FTP, create a file on your local computer, call it 1.htaccess, upload it to the root of your WordPress install, and then rename it to .htaccess. Now read the following section to see how you can edit the file.

Creating Rewrite Rules (.htaccess)

Your server must have mod_rewrite for cruft-free permalinks to work. In addition, you must create a .htaccess file and place it in the directory in which your main index.php file resides, or make that directory writable so that WordPress can do this for you. For example, if your WordPress blog is installed at domain.com/wordpress/, put the .htaccess file at domain.com/wordpress/.htaccess. However, if your WordPress installation is in a subdirectory, but your visitors access your site at the top level of your domain, place the .htaccess file at domain.com/.htaccess.

When you create a permalink structure, WordPress will generate rewrite rules and attempt to insert them into the proper .htaccess file. If it can't, it will print the rules out for you to copy and paste into your .htaccess file.

A few notes about creating and editing your .htaccess file:

Using Permalinks Without mod_rewrite

For cruftless permalinks, you must use mod_rewrite, and IIS (common on Windows servers) does not support mod_rewrite. If you are using Apache 2.0.54, on Windows, mod_rewrite may work. If you put a filename at the beginning, WordPress will attempt to use that to pass the arguments and bypass the necessity for mod_rewrite.

/index.php/%year%/%monthnum%/%day%/%postname%/

If you use this option, you can ignore the rewrite rules (that is, you can ignore .htaccess).

cgi.fix_pathinfo = 1
cgi.force_redirect = 0

This reference from Cem via http://blog.taragana.com/index.php/archive/wordpress-tip-on-permalink-options/

Another solution exists using IIS' custom 404 redirects.

It requires that your web host allows you to add a custom 404 redirect, but it doesn't require you to install any 3rd party mod_rewrite software and it also doesn't require that your permalink structure begin with /index.php/...

Here is the link to the installation files and instructions:

http://www.keyboardface.com/IIS-Permalinks/

Fixing Permalink Problems

Fixing (.htaccess) Generation Issues

If your installation of WordPress does not generate a .htaccess file or if it does not write the new rules onto your existing .htaccess file then there are a couple reasons that could be causing this. Work step by step and continue to the next step only if the previous step does not work.

  1. Change File Permissions: You must chmod the .htaccess file to 666 to edit it with the WordPress template editor, but this is not recommended, since if you do that, any user of your blog, who can edit templates will be able to edit it. You can change the permissions to 660 to make it server-writable, which again will have the same limitation.
  2. Server Blockage: Your host might have blocked the SERVER_SOFTWARE variable and this will cause WordPress' .htaccess generation to fail. If you are sure that your server is running Apache, you can force WordPress to believe that your server is running Apache by changing your wp-includes/vars.php file. Follow the steps below to implement these changes.
    1. Open the wp-includes/vars.php file using the built in file editor in your WordPress Admin panel. To navigate to this panel, login to WordPress, click on "Manage", then on "Files", scroll to the bottom and type in wp-includes/vars.php into the text box under the "Other Files" title.
    2. Look for $is_apache = strstr($_SERVER['SERVER_SOFTWARE'], 'Apache') ? 1 : 0;, once you find it replace it with // $is_apache = strstr($_SERVER['SERVER_SOFTWARE'], 'Apache') ? 1 : 0;
    3. Add a new line under // $is_apache = strstr($_SERVER['SERVER_SOFTWARE'], 'Apache') ? 1 : 0; and type in $is_apache = 1;

Permalinks, .htaccess, and MS Frontpage

A note about Microsoft Frontpage, many servers (shared and dedicated) maintained and built by various hosting companies come with mod_frontpage compiled with the apache build, and in many cases with the Frontpage Server Extensions installed, on each virtual server. This is more common than not, many/most binary distributions used in the server build process at most hosting companies these days include both mod_fronpage and the server extensions. Even if you're not using Frontpage, because of the way that the extensions interact with apache (and the httpd.conf file) you'll likely get something like a 500 error or blank white page when trying to view your WP install (although the admin panel may operate correctly) simply because the extesions/mod_frontpage exist on your server.

Wordpress will operate correctly with the Frontpage Extensions installed, however permalinks will not function at all and ANY change to the permalinks section from the Wordpress admin interface will cause corruption of the Frontpage server extensions due to the addition of the mod_rewrite rules to the .htaccess file. There is however now a fix for this situation.

Quick Fixes, Frontpage or Permalinks

Frontpage Extensions Fix: If you don't care about permalinks and just want to make the MS Frontpage server extensions work again, simply edit your .htaccess file and remove the wordpress section with the rewrite rules.

To Use Permalinks: If you don't care about Frontpage(but your hosting company has the extensions installed) You will need to remove (or have your hosting company do so) the MS Frontpage server extensions, or simply edit the .htaccess file to removed all of the Frontpage Lines, leaving only the wordpress mod_rewrite code.

Using Frontpage AND Permalinks Together

Finally, A solution.

There have been a number of threads on this issue in the support forums, and until now, no solution to the problem.

Normally, on a Unix server with the Microsoft Frontpage Server extensions installed wordpress works just fine and you are able to edit and publish pages (with MS Frontpage) - UNTIL - you make a change to the permalinks (for example to the date based kind that I like /2005/04/etc). I often suggest that type of URI to folks asking about permalinks etc, as that is the method recommended by the w3c (see http://www.w3.org/Provider/Style/URI ).

Now, the problem is that MS Frontpage uses the .htaccess file (which the wordpress mod_rewrite rules must go into) for it's "publishing" and "web authoring" configuration. As soon as the wordpress mod_rewrite code is added to the file, two things happen - the permalinks don't work, and the MS Frontpage Server extensions become corrupted.

I have tried countless ways to get around this, including trying to use rewrite rules that "ignore" the %{HTTP_USERAGENT)% used by Frontpage, to using a second AccessFilename .wpaccess to the httpd.conf file, and a host of other things, and nothing worked so that a person would be able to both use MS Frontpage to manage the website and use the permalinks for wordpress at the same time.

The solution is acctually quite simple, and I kind of figured it out by accident.

If you are using or wish to use MS Frontpage (or that's just how your hosting company has things configured) along with wordpress you'll need to take the following simple steps on your server (or have your hosting company do it for you).

MS Frontpage creates the following directory _vti_bin

Nested within that it creates both _vti_adm and _vti_aut

In addition to in your website (or wordpress) root folder in all of those directories you will find additional .htaccess files.

In all three of these directories AND in the root directory, at the top of ALL of the .htaccess files you simply need to add one line -

Options +FollowSymlinks

There may or may not already be a line in each like Options None Edit and save each .htaccess file and you're done. Now everyhting works perfectly, including MS Frontpage, AND the permalinks of your choosing.

A Final Note

On a personal note, I prefer to use Frontpage to manage/maintain sites, I've been using it since around '96, and by now, since I do most work on UNIX servers anyway I have it configured to use external editors for just about everything, including Zend Studio for php files, Bradbury TopStyle for stylesheets, Adobe ImageReady/Photoshop for images, etc. I'm more or less just using Frontpage as a convenient way to manage the site and access everything, etc. Then when I hit the "save" button in any of the other applications, they have Frontpage save my changes directly to the server, with no need to be FTP'ing files around, etc. It does help to get lots accomplished very quickly, and I was pretty bummed for the past year or so with the permalink frustration, since I was either needing to not use permalinks or not use Frontpage, or keep re-installing the FP extensions. At one point I found a way to make a .htaccess for my "running" site, but then change it to a FP .htaccess when I was doing any work (permalinks of course didn't work), either way it was a real pain.

This should work with most versions of FP and most of the unix versions of the extensions in use today.

--Chradil 17:24, 17 May 2006 (GMT)

Long Permalinks

When using extra long permalinks in email and posting in comments and chats, some long permalinks are "chopped off" or only the first section is actually recognized as a link and the end seen as text. Here is an example.

http://yourdomain.example.com/2005/10/4/article-about-joe-fred-sally-and-bog

Can result in:

http://yourdomain.example.com/2005/10/4/article-about-joe-fred-sally-and-bog

To click on the lower link, the user would get a 404 Page Not Found Error. If you have a tendency to use very long permalink post titles, take these steps to prevent this problem.

1. Check that you are indeed using Permalinks.

2. Edit your .htaccess file and add the following and save the file:

RewriteRule ^post/([0-9]+)?/?([0-9]+)?/?$ /index.php?p=$1&page=$2 [QSA]

3. Test it. Find a post's ID number and type the following (with your information) in your browser and you should be redirected to your post:

http://yourdomain.example.com/post/(the ID #)

It is also worth noting that most email software will not cut off URLs that have been delineated with angle-brackets (< and >), so when pasting URLs into emails, you should write them as so:

Read my blog post at <http://yourdomain.example.com/2005/10/4/article-about-joe-fred-sally-and-bog>

Fixing Other Issues

If your .htaccess file is being generated correctly, but Permalinks still do not function, the following might be a problem. If problems persist, post a note in the WordPress Forum's (http://www.wordpress.org/support) How To section.

AllowOverride Not Enabled
Your server may not have the AllowOverride directive enabled. If the AllowOverride directive is set to None in your Apache httpd.config file, then .htaccess files are completely ignored. In this case, the server will not even attempt to read .htaccess files in the filesystem. When this directive is set to All, then any directive which has the .htaccess Context is allowed in .htaccess files. Example of enabled AllowOverride directive in httpd.config:

<Directory />
   Options FollowSymLinks
   AllowOverride All
</Directory>

You may also have to enable the AllowOverride directive in your DocumentRoot:

<Directory /var/www/html>
   # ... other directives...
   AllowOverride All
</Directory>

You may also have to change the AllowOverride settings for the site. This is surely the case when using Mac Osx Server, but might be likewise with other systems. Usually you can find the site configuration files in /etc/httpd/sites/
If you don't want to set AllowOverride to all (as it is above) then your AllowOverride list must include the FileInfo directive. You must restart your Apache server for any httpd.config file changes to take effect. For more information on which overrides are allowed, read about Apache Core Features (http://httpd.apache.org/docs-2.0/mod/core.html#allowoverride).
Paged Navigation Doesn't Work
Sometimes navigation to second (and subsequent) pages of posts does not work as expected. Your page may generate a link to a page with one of these URIs:
http://www.example.com/page/2/
http://www.example.name/category/categoryname/page/2/
http://www.example/year/month/day/page/2/
http://www.example/year/month/page/2/
The result of clicking one of those links is that the page loads with all the surroundings (header, footer, sidebar), but instead of a page of posts, there is an error message: "Sorry, no posts match that criteria."
This is due to a glitch in the .htaccess file that WordPress generates. To fix it, delete the contents of your .htaccess file and re-create it.
  1. In the Control Panel, go to Manage > Files (More Info on Editing Files)
  2. Click the link to your .htaccess file to edit its contents
  3. Copy the contents of the file and paste it to a text file in a text editor
    This is a precaution in case your .htaccess file has manual entries for redirects, denials or other handy htaccess tricks (http://www.javascriptkit.com/howto/htaccess.shtml)
  4. Delete all contents from your .htaccess file and click the Update File button.
  5. In the Control Panel, go to Options > Permalinks.
  6. Click the Update Permalink Structure button to freshly generate new rewrite rules for your permalinks.
  7. Test the results using a link that had previously broken.
  8. Add any manual htaccess entries back in your file
    (Place manual htaccess entries before the # BEGIN WordPress or after # END WordPress lines.)
You may also perform similar steps by deleting the .htaccess files from the server, creating a fresh empty .htaccess file, changing its permissions to 666, and then in Options > Permalinks generate a new set of htaccess rules by clicking the Update Permalinks Structure button.
If that still doesn't work, take a look at the wordpress support forums, specifically, this support post (http://wordpress.org/support/topic/51613#post-283222).
Permalinks to pages don't work
If you've tried to navigate to a newly created Page and encounter an error, you likely need to update your Permalink structure. Remember, each time you add a new static Page to WordPress, new rules must be generated and updated to .htaccess
Permalinks work but no pages are returned
Some versions of PHP 4.4.x and 5.x have a bug that causes mod_rewrite to fail when used with some versions of Apache 2.x. More details at http://bugs.php.net/bug.php?id=35096 and http://bugs.php.net/bug.php?id=35059.

More Help

If these steps do not work, search for your problem in the Codex (http://codex.wordpress.org), Troubleshooting, or in the Support Forum (http://wordpress.org/support/). As a last resort, file a bug report.

Tips and Tricks

Having your posts end in .html

There's an easy way to having your posts end in a .html extension, using the structure tags above. Following the example used on properly terminating permalinks, you could have a page like http://yoursite.com/2006/01/01/happy-newyear.html with this rule:

/%year%/%monthnum%/%day%/%postname%.html

Note that this does not generate actual .html files. It is only an illusion. There is no benefit to this... some people mistakenly think it offers search engine benefits, and some want their permalinks to emulate those of another publishing system.

External Resources

Retrieved from "http://codex.wordpress.org/Using_Permalinks"