How to fix “broken image captions” in WordPress 3.4

We’ve been discussing an issue with broken captions at the WordPress forum over the last few days. It appears that due to a code change in the WordPress core, captions are now inserted in a different way. This is to allow for HTML in captions which was not possible beforehand.

Turns out that many themes have not been updated to make use of this. Sadly this means that many users are left hanging with themes that are no longer compatible with the latest version of WordPress.

Lets take a look at the problem and see if we can fix it.

The Problem

First and foremost: existing posts are not affected by this issue. Only when you create a new post or add a picture with a caption to an existing post will this issue manifest. It’s not even an issue as far as WordPress are concerned; it’s more like a “necessary upgrade that’s fully backwards compatible”.

If you’re using the captions feature and suddenly your images have a caption like this:

instead of a nicely formatted caption within the picture frame as they used to have (like this):

then your theme has not been updated yet. No future WordPress fix is going to bring your captions back I’m afraid.

How does this happen?

Here’s what happens when you’re inserting a picture with a caption in WordPress 3.3.x and before:

Since WordPress 3.4 the caption is inserted like this:

You can see why this change was made: inside the caption=”…” there wouldn’t by any room for HTML. Why we need HTML in captions is another issue – I can’t see an application for this myself at the time of writing (but hey, I’m not as cutting edge as the rest of the world I guess).

The Solution

There are two solutions to this problem: the easy (yet annoying) option is to manually bring your caption back to where it should have been. Head over to edit the post in question, then select the HTML editor. Find the caption you want to amend and simply change the format to what it used to be (i.e. use caption=”My Caption” inside the caption tag).

If you do this, make sure you hit Publish while you’re still in HTML view. Should you switch back to the Visual Editor all your amended captions will be lost and brought right back to WordPress 3.4 style.

The other solution is to wait for your theme developer to upgrade your theme. Thesis have already offered a patch for this, and I’m sure other premium developers will follow suit shortly.

However if you’re using an older theme that’s no longer supported you may be stuck. I’ll see if there is a simple code replacement that can work for several themes. If I figure it out I’ll let you know.