In case you weren’t already aware this site or blog, whichever you prefer, is running on Mac OS X Leopard 10.5.2 (not server) and is powered by the WordPress blogging engine. Because this site is running on a simple Mac mini with Apache enabled the project is extremely “DIY” and as such I have had to figure it out as I go along. No fancy hosts or one-click installs here, everything has been extremely manual; except, of course, the Famous 5 minute WordPress Installation!
One hurdle I have had to overcome is being able to use pretty permalinks to make my site more friendly. Permalinks (short for permanent link, get it?) is a static URL to some content on a site. That content can be a specific page, a particular article/post, or a collection of posts within a certain category.
By default WordPress’s permalinks follow this format: http://somesite.com/index.php?p=1 and unfortunately that format is just plain ugly. Having a pretty permalink like this: http://somesite.com/2008/01/01/sample-post/ means hyperlinks on your site and around the web will be more attractive and usable to others.
Read on if you want to know my story about the trouble and success I had with getting pretty permalinks working on my site.
For those of you with nice hosts that integrate well with WordPress and have fancy one-click installers chances are that all you have to do to enable pretty permalinks is choose your format and turn them on under settings. I hate you.
When I tried to enable them the first problem I received was that the directory was not writable. An FAQ entry I found at Laughing Squid Web Hosting is where I started my search for a solution. It turns out WordPress needed to change my .htaccess file and the permissions on my server wouldn’t allow it. Well, because my level of knowledge was basically non-existent on the subject I started fiddling around and doing research on permissions.
One of the best articles I found was one over at elated.com and introduced to me by Google (thanks!); the article is here and if you are curious about permissions in a UNIX-based operating system it’s a very good read. Besides being written in fairly plain english it even provides a handy chart so you can know what permissions will be set when you “chmod 755 directory“.
Armed with enough knowledge to be dangerous I created a blank .htaccess file in my site’s root folder (pro tip: in Leopard, the root folder for Apache is /Library/WebServer/Documents, for your server this may be different and it is entirely possible to change it as well). Lastly I set its permissions to 666 (scary, I know) so WordPress could edit the file.
chmod 666 .htaccess
Once this was done I went to settings and enabled permalinks; then I went to the main page and tested it out by excitedly selecting a post. 404. Not exciting at all. There was clearly a problem. Besides being flustered I had to disable permalinks so my readers reader (Hi Dad!) could actually access content on the site without a confrontation with the aforementioned 404.
Stumped and discouraged, I gave up for awhile… Until recently, as it turns out there was an email I had received from the famous Christina Warren that mentioned the vast amount of help articles available in the WordPress Community.
I scoured them and quickly found this article hepfully titled “Using Permalinks”. Reading through the article I came across some points that seemed relevant but were far over my head; they mentioned something about “FollowSymLinks” and “Directives”. Down but not out I pressed on and learned that my httpd.conf file, Apache’s configuration file, needed some work.
In Leopard, this file is located at /etc/apache2/httpd.conf – and you’re welcome because it took me awhile to realize it had moved from its old location in Tiger. The first thing I had to do was to check to ensure that mod_rewrite was enabled; according to WordPress mod_rewrite is an extension module of the Apache web server software which allows for “rewriting” of URLs on-the-fly. This, simply put, is what makes it possible for the server to translate and understand a pretty permalink.
To enable this you have to uncomment the following, which can be found at line 112:
LoadModule rewrite_module libexec/apache2/mod_rewrite.so
and then restart Apache.
sudo apachectl graceful
This will probably ask you for your password, so type it in and hit <enter>. Once you have done that Apache will gracefully shutdown and restart with mod_rewrite enabled. At this point I was not done, but you are free to go ahead and try to enable permalinks and see if you don’t get a 404; if you do then you are probably in the same boat I was and need to make some more changes to your httpd.conf file.
According to my handy, dandy permalinks help article I needed to enable a directive that would tell Apache to look at my .htaccess file that was created earlier and then edited by WordPress when permalinks were enabled. Here is an example of the AllowOverride directive enabled in httpd.conf in Leopard, it is at line 173:
Deny from all
It was also necessary to enable the override in Apache’s root folder. In Leopard’s default httpd.conf file the directives for Apache’s root folder have lots of comments around them unlike the directives for the OS root “/”. In httpd.conf scroll down to line 210 and change it to be “AllowOverride All”.
When you have finished editing the httpd.conf file restart Apache like we did above. At this point, with fingers crossed, I re-enabled pretty permalinks; WordPress said it was successful but history dictated otherwise. I pulled up the main page, selected a blog entry and Boom! Ugly permalinks were a thing of the past! I discovered that this effected not just my blog posts but my pages, category view, and tag view as well.
This site and its underpinnings are continually changing and, in my opinion, improving. I am learning a lot every time I dig into it. I hope this helps somebody because I know I couldn’t find one resource that had all of this information anywhere! If you have any questions feel free to leave them in the comments or get a hold of me directly via Twitter or email.