Have you ever needed to change the URL for your website? Say, move your website from one domain to another, from a subdirectory to the root of a web host, or even make a copy? Chances are, you’ll find broken links and missing images in the text of your content.
Although Drupal handles internal links, like menus, wonderfully, internal links in text areas like WYSIWYG fields are not handled as gracefully. For example, if a site is moved from one domain to another, from a subdirectory to the root of a web host, or if a page is moved in the URL hierarchy, the links in the text areas may no longer be accurate. How can you find and update all of those broken links?
We have Pathologic to the rescue! Pathologic is Drupal’s solution for fixing broken links and paths to images in the text areas of your site, and this handy module is available in Stanford Sites.
How Pathologic works
Drupal defines text formats to control formatting and processing when editing text and HTML in a text area. These text formats define filters and formats to be applied when text is output to the page. To learn more about text filters visit Text Filters and Input Formats. For example, a Text Format may use an input filter to close all HTML tags before saving content.
Similarly, Pathologic provides an input filter that detects links in a text area and adjusts the links when you’ve moved your site or changed your URL. That is, it takes URLs from the previous site location and updates them for the current site location. The URLs that Pathologic will update include links and paths for images. Note that since Drupal filters text on output, your original text remains the same; Pathologic will change the URLs when the page is rendered for display.
Configuring Pathologic
Before making any changes to the URL for your site, you’ll want to configure Pathologic.
Start by installing and enabling the Pathologic module
To enable the module:
- Navigate to Modules (admin/modules)
- Search for Pathologic
- If not checked, check the box for Pathologic
- Scroll to the bottom of the page and click on Save configuration
Enable WYSIWYG (optional)
If you will be using a WYSIWYG editor, you'll want to enable and configure that first. For those sites hosted on Stanford Sites, we use the Stanford WYSIWYG module available on Github. This module can be enabled following the directions for enabling a module above, substituting the "Stanford WYSIWYG" module for the "Pathologic" module. The Stanford WYSIWYG provides the "Content Editor Text Format" referenced below. However, you can configure Pathologic for any text format.
Add Pathologic to desired Text Formats
-
Navigate to Configuration > Content Authoring > Text Formats (admin/config/content/formats)
-
Select configure for the text format you want to configure, (e.g. on Stanford Sites, you’ll probably want to configure "Filtered HTML" or on a Stanford Jumpstart Site, “Content Editor Text Format”)
-
On the configuration page, scroll down to Enabled filters
-
Check Correct URLs with Pathologic
-
Under Filter processing order, if necessary move Correct URLs with Pathologic to be the last filter in the list
-
Under Filter settings, select the Correct URLs with Pathologic horizontal tab
-
In the text field, enter the URL paths of the current and previous installation of your site (e.g., https://sites.stanford.edu/mysite/)
-
If this Text Format uses a WYSIWYG, enter the full subdirectory path with slashes at the beginning and end (e.g., /mysite/)
-
Enter "/" in the "all base paths for this site" section. That way, you can enter "/foo/bar/baz" in the WYSIWYG link editor and it will get filtered to "https://sites.stanford.edu/mysite/foo/bar/baz"
-
Scroll to the bottom and click Save configuration
-
Navigate to a page with an image or a link, and check that it is displaying as expected
Adding links
With Pathologic configured, these links will render equivalent results (https://sites.stanford.edu/mysite/news):
- https://sites.stanford.edu/mysite/news
- /news
- news
To add a link to text in the WYSIWYG
- Select the text to display
- Click on the link icon to bring up a link dialog box
- Paste the destination URL into the URL field
- When the URL is within your site, you may enter the local URL (e.g., "news") without an initial "/". Then, in the Protocol drop-down, select <other>
Troubleshooting
If images are still not displaying properly, you may need to clear the cache for your changes to take effect.
To Clear the Cache
Visit Administration > Configuration > Development > Performance (admin/config/development/performance) and clicking the Clear all caches button near the top of the page.
More Information
For more information on Pathologic, visit the Drupal.org project page at: https://drupal.org/project/pathologic, and read the documentation at https://drupal.org/node/257026.
