Enabling SEO Friendly URLs in MODx (part VI in the series)

May 26, 2009 - Reading time: 7 minutes

Many content management systems rely on URL parameters like ?page=3 to determine which page is displayed to the user. MODx (like many other CMS’s) can use Apache’s .htaccess file to rewrite URLs so they are easier to read, e.g. www.mydomain.com/modx/tutorial, and this usually results in higher SEO scores. This article and its video walk you through how to accomplish this for MODx running on an Apache web server. Windows servers have something similar, they just charge more for it (haha).

Here’s the video. I was going to re-do this in high-def, but this was one of those lightning-strike rants that I was on… I just know it wouldn’t be as good if I attempted to remake it.

* I mispronounced MODx in the video (sorry). It should be “mod” as is “modular”.

The Quickie Text Version of the Video

1. Make sure MODx is installed and your site works.
2. Go to the root of your site, verify that you have an .htaccess file (MODx often includes a dummy file named “ht.access” which needs to be renamed before it is parsed). Be sure to keep a backup copy of the original!
3. Edit the .htaccess file and type some junk at the very top of the file. For example, type in “asdpfasdfj” at the top of the file, then save it. Now try to visit any page on your site. You should get an server error, and this is GOOD! This means that the .htaccess file is being parsed, so go back and delete that junk from the file. If you don’t get an error, it means that the .htaccess file is NOT being parsed, and you may need to contact your ISP to see how to enable it. You can’t get friendly URLs working without this!
4. Once you’ve confirmed that your .htaccess file is being parsed, you can make the appropriate edits (see below). The dummy file included with your MODx install is very well annotated. I’ve listed the most important bits below (please change yourdomain to the appropriate domain). Note that in some of the lines, you must precede periods with a backslash (i.e. you must escape them). Any line starting with “#” is a comment.
# Vital components of your .htaccess file
RewriteEngine On
RewriteBase /

   # Force “www.yourdomain.com” instead of just “yourdomain.com”
   RewriteCond %{HTTP_HOST} .
   RewriteCond %{HTTP_HOST} !^www\.yourdomain\.com [NC]
   RewriteRule (.*) https://www.yourdomain.com/$1 [R=301,L]

   # The Friendly URLs part
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

5. Make sure your site is still working… you can still use the same un-friendly URLs after making these edits; you just want to make sure you didn’t misspell something in your .htaccess file and cause it to parse incorrectly.
6. Login to the MODx manager (www.yoursite.com/manager) and go to Tools->Configuration->Friendly URLs and change the following settings:
   * Use friendly URLs: YES
   * Use friendly aliases: YES
   * Use friendly alias path: YES

You should now be able to navigate to pages by using their alias!

More Information

Friendly URLs Guide — From the MODx Wiki.

Technical Details about .htaccess

What exactly is happening? Well, the .htaccess file can control a lot of server settings, and you can think of it almost like a style sheet: the server has global settings, but the .htaccess file provides a way to override some of those settings locally for a particular directory or site. It really merits its own article (stay tuned), but let’s look at the the friendly URLs part of the .htaccess file.

The core of this functionality is Apache’s mod_rewrite module. My snarky description is this: it lets the server lie to your address bar! Your browser window may SAY that you are visiting www.mydomain.com/modx/tutorial, but really, the page you are viewing (on a MODx site) is:
www.mydomain.com/index.php?q=modx/tutorial
Try this on your own MODx site! You should see the same page as you did when you visited the friendly URL.

Here’s what the .htaccess file is doing. The first RewriteCond is checking the file system for a file of the name you are requesting. In the example, it’d look for a file named “tutorial” in the “modx” directory. The “!-f” at the end of the line is basically saying “IF there isn’t a file of this name”… then the next line’s “!-d” says “OR there’s not a directory of this name”, THEN perform the rewrite defined by the RewriteRule.

Here you see a good example of a regular expression, and if you haven’t heard that term before, I can sum up quickly: if you’ve ever done a “search” or a “find and replace” in a document, you’ve utilized a simple type of regular expression. A regular expression searches for a pattern. The $1 is a common shorthand notation that back-references what exactly was found, in this case, it’s the argument that’s being passed to the server for the REQUEST_FILENAME, i.e. “modx/tutorial”. The contents of the $1 variable is then added onto “index.php?q=” and you end up with the REAL URL being:
www.mydomain.com/index.php?q=modx/tutorial

Tricky tricky! I skipped over a lot of details for this brief overview, but hopefully you can see some of the process here. This is how most CMS’s handle this sort of thing. The .htaccess parsing requires more overhead from Apache, but it offers a lot of flexibility in how you access your files, and for most sites, this is a very worthy tradeoff.

-- Everett Griffiths