Pathologic is an input filter for Drupal which attempts to make sure that links to other content in your Drupal installation, as well as images and other media, will always work correctly; the links won't "break" in situations which would otherwise cause them not to work. Maybe it could be explained better by listing some situations where Pathologic would come in handy…

• You run a personal site, and the address of your site recently changed. Perhaps you moved to a shiny new domain name, or perhaps you moved the Drupal installation from one subdirectory to another. Now all the images in your content are broken, as well as links to other content on your site. You could go through all your content and update all the links… or you could install Pathologic.


• You oversee a site which has testing and production servers. Copy-editors (and/or you) edit content on the testing server, and that eventually gets pushed over to the production server. When those darn editors link to other content on the site, they sometimes link to the version of it that's up on the test server; these links break when the content is published on the production server. You could flog the editors (and/or yourself) with a bullwhip for each infraction… or you could install Pathologic.


• Your Drupal site has been up for a while, but you've recently discovered the Clean URLs feature and enabled it. Your links still work, but they still have that ugly "?q=" thing in them, and you have better things to do with your time than go through all your content to prettify the links. Or maybe you're going the other way; you used to have Clean URLs enabled, but you've had to disable it, and now your links are broken. Pathologic to the rescue!


• Your site content uses relative paths (eg, <a href="tag/food/pizza"> which break for people reading your site's feed. You could just start using absolute paths instead, but you're too set in your ways and would rather have a tool do it for you.

Pathologic is designed to be a simple, set-it-and-forget-it utility. You don't need to type any special "tags" or special characters in your content to trigger Pathologic to work; it finds paths it can manage in your content automatically.

Installation

Pathologic is an input filter, so getting it installed and configured is a little bit more difficult than standard modules, but the instructions below will walk you through the process.

• Install the Pathologic module as normal.


• In the Administer menu, select "Input formats" from the "Site configuration" section. A list will appear of the various input formats your site uses. Find one in the list which you want to use Pathologic with, and click the "configure" link for that format.


• On the next page, find the section labeled "Filters." Check the box next to "Pathologic." All other options on this page can be left alone. Click the "Save configuration" button at the bottom.


• This will take you back to the same page, with a message telling you "The input format settings have been updated." Now, find the "Rearrange" tab at the top of the page and click it.


• This will bring you to a list of filters that this input format uses. Pathologic should be at the bottom of this list; if so, you don't have to do anything. If it is not, adjust the values in the "Weight" column so that Pathologic has the highest value. Click "Save configuration" when done.


• If you wish to use Pathologic with other input formats, go back to step 2 and repeat the process.


• Pathologic is now working on all old and new content which uses the input format(s) you added it to.

Configuring Pathologic

If you've determined that configuring Pathologic may be necessary, here's how to go about it.

• In the Administer menu, select "Input formats" from the "Site configuration" section. A list will appear of the various input formats your site uses. Find one in the list which you are using Pathologic with, and click the "configure" link for that format. (Note that if you are using Pathologic with more than one input format, you will have to repeat this configuration process for each input format.)


• Click the "Configure" tab at the top of the next page.


• Find the Pathologic section on the next page — it should be near the bottom.


• Toggle the "Transform values of href attributes" and "Transform values of src attributes" check boxes as may be necessary.


• Enter the paths of other/previous Drupal installations which should be considered local in the "Additional paths to be considered local" text field. Enter one path per line. For the above example, we'd want to enter http://example.com/drupal/.


• Click the "Save configuration" button when done.

(Note for those using testing and production servers; in cases where it would be inconvenient to have separate settings on each server, it's safe to put the path for the "current" server in the "Additional paths" field. Pathologic will simply remove it when it does its trick. In other words, both the example.com and example.net servers can have both http://example.com/drupal/ and http://example.net/ in the field.)