How To Insert Links Inside Of Image Captions

Occasionally, I ‘ll take a look through the WordPress Ideas site to see what kind of activity is going on. The other night, I discovered an idea that immediately lit the light bulb over my head, mostly because I couldn’t believe that it was not already a feature in WordPress. Approximately one year ago, Jeremy Clarke submitted the idea to allow URLs to be inserted into image captions with the primary goal of making it easy to attribute images to their source. I’ve personally come across the issue where instead of applying the image credits within the image caption, I have to add a note somewhere within the post which is stupid since image captions are the PERFECT spot for attribution. Fast forward to October 18th, 2011 with WordPress 3.3. knocking on the door and this ability is still not present within WordPress. However, there are a couple of things that point to this feature being added soon as the status for the idea is marked Good Idea! We’re Working On It. There is also a ticket in trac, #18311 that has a patch but is currently awaiting review.

While there is not a native, user-friendly way of adding links to image captions, there are a couple of ways in which it can be accomplished. The first is by using ‘ instead of ” when entering the code for your link. However, when switching between the code and visual editors, the link is erased leaving text in place of the link.

Second, you can try using the code provided by Kaspars of inside of your functions.php file which will add a “Source URL” field to every image that is uploaded through the WordPress media library. When using this method, it’s important to note that the source URL will be visible only if you specify an image caption upon inserting the image. If implemented correctly, it will look something like this.

Adding An Image Source URL Field

Third, you can try using the Links In Captions Plugin by Zack Katz. After activation, you can add links to captions via the following format: {link url=””}Anchor text here{/link} Two benefits to this plugin is that it has support for the Target and Rel attributes and you can use shortcodes within the caption area.

Personally, I think Kaspars solution is the most user-friendly after the functions.php file is setup correctly. I’d like to see him package that as a plugin so more users can take advantage of it as it looks as though it was part of the media manager all along. However, the best scenario is for this functionality to some how end up within the core of WordPress. If you have the know-how, please consider contributing to the ticket or writing a better patch to get this into core.


  1. In the efforts of full disclosure, I’m the one who moved it to ‘Good idea, we’re working on it’ based on the related trac ticket being accepted as ‘Yeah, good point!’ As the patch was added 3 weeks ago, it won’t make it into 3.3 for sure.

    I like Kaspar’s fix too, and with that in mind, I’m cross-referencing that to trac!


  2. The idea sounds good. It will help in making blogs more trustworthy and talented photographers will get credit for their work. But the point is, how many people will actually use it?

    Its good to provide a feature but why over load a beautiful yet simple wordpress framework with it.

    Its better if there is a plugin for this or something in between.


  3. you mention one thing that’s still nagging at me since I ran into it more than a few times with the last site we worked on. It’s nearly 2012. Why are we still having problems with disappearing content and markup when switching between the visual and html editors?


  4. @Ipstenu – I’ve noticed that you’ve been the one pruning and going through the ideas area lately. Glad someone’s doing it! I had thought that someone from the core team marked it as a good idea but it makes sense considering the trac ticket and all.

    @Abhishek – I think a number of people would end up using it since so many people use images that they didn’t create.

    @Scott R. Godin – This interview I conducted with Andrew Ozz in 2009 might shed some light on that.


  5. @Abhishek

    I agree that this functionality is Plugin territory, but I won’t complain if it does make it into core. I would find it occasionally useful.

    @Scott R. Godin

    It is deliberate design intent. WordPress assumes, and intends, that the user will choose either the Visual editor, or the HTML editor, but not both during the same editing session. If you want to be able to switch between the two, it is simple enough to filter the TinyMCE init configuration to prevent the wonky behavior caused by the switch.


  6. The reason the caption doesn’t display links is because it is using the excerpt, which doesn’t store links. You can put links in the description (which uses the post content).

    In a theme I’m building right now the client wants the featured image displayed with the caption, and the caption needs links in it. So I’m using this:

    the_post_thumbnail( 'be_featured' );
    $caption = get_post( get_post_thumbnail_id() )->post_content;
    if( !empty( $caption ) ) echo '<p>' . $caption . '</p>';

    This doesn’t work with the “Insert into Post” though since that still uses the excerpt.


  7. Hey Jeffro thanks for writing this up! What a mess this situation is. I just spent a few hours investigating the underlying code to figure out WTF is going on and what we might be able to do to fix it. I updated the trac ticket with a LOT of info and ideas in case anyone is interested:

    It’s a huge mess with lots of contributing factors blocking HTML from being present in caption text. Fundamentally it comes down to the fact that the caption text is stored in an attribute of the [caption] shortcode, rather than between [caption] and [/caption]. The result is that it can only have the kinds of things that normally make sense in an HTML attribute (attributes are things in html tags like href or src), which notably does not usually include other HTML tags! Ideally we’d rework the shortcode entirely, which would suit me fine because it has never really seemed like the right way to me, but is probably never going to happen.

    Instead if we want links in captions we’ll probably need to hack them in with some crazy mess of code as well as writing a lot of supporting code for other parts of the admin UI that deal with images and captions. Ugh.


  8. @Chip Bennett

    It is deliberate design intent. WordPress assumes, and intends, that the user will choose either the Visual editor, or the HTML editor, but not both during the same editing session.

    I really don’t think this IS or SHOULD BE the way WordPress core developers view editing. In my experience normal users switch back and forth regularly to write code that can’t be generated by WYSIWYG and to check/validate what the WYSIWYG is doing behind the scenes. This is totally natural and something that is implied to be okay by the UI which makes switching back and forth so easy.

    Also remember that posts can be edited by multiple users, so even if one user has Visual Editor turned off in their settings, another user can come and without even noticing, simply by opening the post editor, completely mess up formatting that the non-visual user had created. This is a huge problem, and the only solution, unless you are the only person who can edit your posts and you NEVER use the visual editor, is to avoid any formatting that will get broken by the visual editor. I do this by switching back and forth if I’m ever in the HTML editor and not sure if a given bit of code will work when switched over.

    Avoiding all non-WYSIWYG-compatible HTML is not ideal, but assuming that users will only use one or the other is just not realistic, and I hope that isn’t what “WordPress assumes” because if so it’s fantasizing.

    If you want to be able to switch between the two, it is simple enough to filter the TinyMCE init configuration to prevent the wonky behavior caused by the switch.

    “Simple enough” is pretty relative. Most people need solutions that work out of the box, and in this case having links in captions is not something, at least IMHO, that should involve avoiding the Visual Editor entirely or having to install/write plugins that hack it’s internal behavior.


  9. @Bill Erickson

    The reason the caption doesn’t display links is because it is using the excerpt, which doesn’t store links.

    Hey Bill, FWIW I think you may be misidentifying the cause of the filtering. the_excerpt filter isn’t involved in the caption text in any way, instead it’s code in the filtering function that processes the caption text before sending the shortcode to the editor ( image_add_caption() ). It strips out , ‘ and “, then runs addslashes() on whatever is left. This code is important because as things stand if those characters are present in the shortcode attribute then the shortcode display functions will choke on them when you load the actual post.

    The strange part is that the media uploader box saves whatever text you give it without filtering, so that even though when you insert the caption the HTML is stripped out, it’s still there in the database, which allows your example code to work by accessing the caption property directly rather than depending on the inserted shortcode. IMHO that should probably be changed, so that the uploader settings match the actual output you get when you insert the shortcode into a post.

    That said, maybe your method is on to something. If the shortcode used the database rather than it’s own attributes to fetch the caption text then the text wouldn’t have to work as an attribute, and would be much more powerful. The problem is all existing caption shortcodes would have vestigial text that is unused, and it would become impossible to edit the caption text from inside the HTML editor.

    Oh bother.


Comments are closed.