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

Apache .htaccess Rewrites are Powerful
Apache .htaccess Rewrites are Powerful

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 (.*) http://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.

4 thoughts on “Enabling SEO Friendly URLs in MODx (part VI in the series)

  1. A very clear and concise tutorial. I did not use the video as I was in a hurry, but your “Quickie Text Version” was easy to follow and I used it to successfully set up friendly URLs for the first time in under 10 minutes.

    Thank you.

  2. You might have heard of “Google bombing”, where many people link to a certain page using certain text and boost that page to the top of the search engines, even though that page might be on a completely different subject. This is because search engines use the words in your link text (otherwise known as “anchor text”) to figure out the nature of the page you’re linking to. This can be used to your advantage in your on-page SEO efforts, giving your pages a little boost for your keywords.

  3. Great tutorial! I really enjoyed watching it! Thank you very very much, it helped me a lot!

    While checking out various CPs for my server, I somehow ran into MODx. I’ve never heard of it so far, but it really looked inspiring to me. Unfortunately, most of the help pages, tutorials I’ve tried, left me back confused.

    Your tutorial was the first one, that really helped. Easy to understand, straight to the point. Need to say more?!

    Thanks again, mate! And keep up the good work!!

Comments are closed.