When I wrote the first version of my blog software in PHP, one of the things I wanted to do was avoid typing links directly into the text. I used a fairly simple str_replace, taking advantage of str_replace’s ability to take arrays as the search for and replace with parameters. The first array contained the “title” of the link, and the second array contained the full “a” tag.

I also told it to only link the first instance of each item in the array, because I don’t like reading things filled with duplicate links.

It ended up getting a little more complicated than that as I fixed issues. The first one was that I had to sort the links by the length of the title, with the shortest titles first—otherwise, a short link might end up creating a link inside of an existing “a” tag created from an earlier, longer title.

Then I realized that this was case insensitive, and not linking text that didn’t exactly match the case of the title, so I switched to preg_replace:

But that, once again, started causing “a” tags within “a” tags, as all lower-case titles with no spaces could easily match hostnames.

And so forth. It still runs the risk of putting a link inside of another link, but it was fairly rare and I just adjusted the link text on the rare occasions when it happened.

Django

When I moved to Django, I initially just used a template tag to handle links. It was precise and linked specific text to specific URLs from another model. But I missed the ability to have text automatically get linked to related links, related pages, and related topics. I ended up writing an Autolinker class; it accepts a list of objects and titles that match those objects. Each object must have a “linkHTML” method that accepts a “title” parameter and creates the link tag with that link text.

It gets used by calling addItem to add individual objects with an arbitrary title, or addLinks to add a list of objects each of which must have a “title” method, and then replaceAll(). Something like this will replace all mention of related topics, related links, or the parent object with linked text to those items:

Each item needs to know how to link itself, and put this knowledge into a linkHTML method; it might look like this:

The template snippet (parts/link.html) would look like this:

What does it do?

It mainly uses Python regular expressions; the bulk of the search is handled by re.sub, but in order to ensure that “a” tags don’t get nested, it sends re.sub a method to call when there’s a match, and that method looks for potential issues.

1. You call the “replaceAll” method with the text to be looked at for potential autolinking. This might be the text of a blog post, or a blurb for a review, or something like that. The replaceAll method goes through each link and calls the “replace” method; it also removes the link from the list; this is useful for looping through paragraphs; it ensures that even if replaceAll() is called more than once for a page’s text, only the first instance of a title showing up on the page gets linked.¹
2. The replace method sets up the replacement object, the needle text, and a boolean for whether or not replacement occurred, as properties on the Autolinker instance. It then calls the “doReplace” method with just the haystack as a parameter.
3. The doReplace method just calls re.sub() with self.needle, a method that will handle matches, and the haystack.
4. The “matcher” method is the guts of it: it takes the match and makes sure that this match is not inside of a Django tag or inside of an existing “a” element. It looks for “a” tags that open but don’t close on the left of the match, and for “a” tags that close but don’t open on the right of the match. If it can’t find either of them, the match is good. It sets the full text to the left text, plus the replacement object’s linkHTML method (called with the match text as the link title), plus the right text. And it marks self.replaced to True, so that the higher methods know that a replacement has occurred.

If necessary, the matcher method calls doReplace again with the text to the right of the match. (The regular expression should ensure no potential matches to the left of the match.)

You can see examples in this post: I typed str_replace and preg_replace bare towards the top of the page, for example, and the Autolinker recognized that it matched the title of one of the related links at the bottom of this post; it then linked that text to the appropriate page.

Caveats

This is going to be processor-intensive for lots of links. I use a Django-based CMS that uploads flat files, so I don’t mind it; if you use Django directly to serve pages, you’ll probably want to perform autolinking on save; for your content field(s), have two columns: one for the raw, unfiltered text, and one for the filtered text. On a save where the raw text changes, filter the raw column to the public column.