Multi-line Captions in WordPress

As my wife and I were each posting our daily photos this afternoon, she asks me to help her put a two line caption under one of her photos. Being somewhat knowledgable about such things, I tell her that I’d be happy to help. And what should have been a very simple task, turned into an hour and a half of messing around and re-writing the captioning capabilities in WordPress. Let me start with a little background. First, let me acknowledge that WordPress is a great blogging platform for text. And I have seen some really beautiful photography blogs created on this platform. But what most people don’t realize is that these photo-blogging themes have a ton of custom code. Out of the box, WordPress is still absolutely awful with regards to text mixed with media. And I do realize that they’ve been constantly updating things, but it’s frankly still a crude environment.

The multi-line captions are a good example. While WordPress 2.5 added the ability to have captions, instead of building it into the user interface and allowing the user / writer to create content to be used as a caption, they instead decided to have the photo import interface add an odd caption shortcode which WordPress will later replace with actual HTML. What this means is that unless you want to modify WordPress core files (a very bad idea since you’d have to do it every time you upgraded WordPress), you’re stuck trying to fix captions within the bounds of their already lacking system. So, without further rambling, here’s the long and the short of fixing the captioning system (a little bit).

Current Implementation (WordPress 2.5+)

Before fixing the captions, we need to understand exactly how it works out of the box.  When you go to insert a photo into a post, if you type anything in the caption dialog, WordPress will insert an image surrounded by a “caption” shortcode.  It goes through and replace this caption shortcode with actual HTML when it’s requested by a reader. However, instead of taking a block of text and including it, all it takes is one lousy string that can’t have anything but text.

Allowing Multiline Captions

Due to the existing implementation, there is really only so much we can work with. We need to take the caption and break it into multiple lines, but remember, WordPress won’t store more than a string for the caption. To fix this, I decided that I’d insert line breaks into the caption based on a text string — in my case, I chose the “|” symbol as I don’t ever see it being used in a caption. You can replace it with whatever you like. To override the existing caption code, edit your theme’s functions.php file and add the following code (note, clicking on the left-most button in the top right of the code box will open the source in an editor — perfect for copying and pasting).

Please note, this will not work when inserting images in the WordPress Gallery format.

/* *********************************************
Function to allow multi-line photo captions. This function will
split captions onto multiple lines if it detects a "|" (pipe) symbol.
********************************************** */
/* Override existing caption shortcode handlers with our own */
add_shortcode('wp_caption', 'multiline_caption');
add_shortcode('caption', 'multiline_caption');

/* Our new function */
function multiline_caption($attr, $content = null)
extract(shortcode_atts(array( 'id' => '',
'align' => 'alignnone',
'width' => '',
'caption' => '' ), $attr));
if ( 1 > (int) $width || empty($caption) )
return $content;
if ( $id ) $id = 'id="' . esc_attr($id) . '" ';

$new_caption = str_replace("|", " ", $caption);

return '<div ' . $id . 'class="wp-caption ' .
esc_attr($align) . '" style="width: ' .
(10 + (int) $width) . 'px">' .
do_shortcode( $content ) .
'<p class="wp-caption-text">' .
$new_caption . </p></div>';

With this done, all that was left was to edit the caption of the desired photo with something like this: “First line of caption.|Second line of caption”.

Additional Resources

In searching the web for a solution, I found everything but what I needed. However, I did find some good resources for WordPress captions in general.

34 thoughts on “Multi-line Captions in WordPress”

  1. Thanks for this. Wanting multi-line captions have been frustrating me for a while now – great solution and works right out of the gate. Cheers.

  2. I just did a quick google search to see if anyone else was having the same problem with multi-line captions… guess so. Thanks for such an easy fix!

  3. Just what I needed for a post with a lot of captions. Thank you so much!

    PS: Suggestion, if you ever have the time: adding simple formatting, like italics and bold. 🙂

  4. Jorge,
    You should be able to control that by adding / editing the classes for “wp-caption-text” and “wp-caption” in your CSS file. Good luck with it!

  5. Thank you so much for doing this, it looks like it will solve exactly the problem I’ve been having. But I’m getting a “Call to undefined function add_shortcode()” error instead of a dashboard. Any tips for getting this into the functions.php file smoothly? I only know to put it between the php tags…

  6. Thanks! This is exactly the fix I need. I think my client can handle adding a pipe to the captions. A lot less frustrating than the other options.

  7. I realize how dumb this sounds, but I copied the above into the functions.php file. But, when I put the pipe symbol into my caption, it shows up in the caption–as a pipe symbol! You all have made it sound so simple, but I’ve been pulling my hair out all day to try to get this. What am I doing wrong? Thanks for any help you can offer.

  8. You rock! And, your SEO for this page was spot-on, found it in an instant and it was exactly what I was looking for. Problem solved, time invested: 2 minutes. Thanks!

  9. Hi, and thanks for this hack, it works perfectly..!

    Do you think it s possible to use your code to add link to captions..? It could be great, cause the links in captions seems to be the next issue of captions.

  10. @Maura did you ever find the answer to this? I am having the exact same issue
    “I realize how dumb this sounds, but I copied the above into the functions.php file. But, when I put the pipe symbol into my caption, it shows up in the caption–as a pipe symbol! You all have made it sound so simple, but I’ve been pulling my hair out all day to try to get this. What am I doing wrong? Thanks for any help you can offer.”

  11. @Maura & @Jaffe,
    When copy / pasting the code to your functions.php file, did you first click on the View Source icon and then copy / paste from there? There’s always a chance that some characters copied might not match up if going straight from the editor window above. Launching the pop-up with View Source should drop any odd formatting you might run into.

    Hope that helps,

  12. I did copy/ paste from the view source icon. Still getting the same issue. Is there any further instruction on using the code other than just copy and pasting into functions.php and then putting a Pipe between caption sentences?

  13. @Jaffe,
    I’m not the author, just trying to help. I assume you’re adding this to an existing functions.php file and placing it inside of the required surrounding PHP tags?

  14. I am. I will continue to work on it. I appreciate the help.
    I have sent a message to the author so hopefully he will respond

  15. @Jaffe – Sorry you’re having issues with this – I have the exact code that is working on my blog in the above post. There are some things which may keep this from working as they should.

    How this whole this works is that the lines “add_shortcode” replace the existing WordPress functions with the multiline_caption function provided above. The line with the str_replace is supposed to replace whatever is in the first set of quotes (in this case, the pipe symbol) with a line break. If this isn’t happening, then I get the feeling that the multiline caption function is not running.

    Possible reasons this could happen is if there are other plugins, themes or functions being used by your blog, which could be inadvertently overwriting the multi-line caption function with something else.

    Hope this helps a little.

  16. So I tried it in the wordpress 2010 theme and still no go.
    I am obviously really dumb and missing something.
    In the post I still just put [gallery] correct?

  17. Hi Jaffe,
    You wouldn’t need to use a shortcode, just place an image from the Media Library (or upload new) into the editor and then add the caption as you’re placing the image, using a | where you want the return. If you’re trying to use this with a gallery extension, that might be the issue.

  18. ah.. yes that was what I was trying to do.. so now the question is.. how do we make this work with the default wordpress [gallery] shortcode.. thoughts.. anyone?

  19. Thanks for your patience Jaffe, and for your insight Jonathan. You are absolutely correct, this won’t work using the [gallery] shortcode.

    If you’re feeling ambitious, it’s possible to open the default WordPress install file named “media.php”. In here, you’ll find the default function “img_caption_shortcode” which is what I’m overriding in my example above. While this is a relatively simple function, directly below it there is a function called “gallery_shortcode”. This is a much more complex function, but in theory you could copy and paste the whole thing into your functions.php file and modify it to do the same string replace I’m performing above.

    Since I don’t actually use the gallery shortcode on my blog, I’m not certain exactly what needs to be replaced, but I think it’s within the “foreach” loop at the bottom of the function which loops through each attached image and displays not only the image, but also the caption.

    Hope this helps a little!

  20. Mark I will give that a shot. Thank you both for all of your help! I will let you know the results just in case anyone else has a need for this sort of thing.

    Thanks again!

  21. So I was able to allow the break with the gallery by removing the strip_tags and just putting a but it only works in the full image not the thumbnail.. I think this is the best route to go and just allow HTML into the caption and title areas of the media.. not perfect yet but it is a start.

  22. Hi

    Thanks for this – a great help! However, I also need to be able to add the pipe in the gallery images !

    @Jaffe can you pls explain more about what you did and perhaps post your code ?

    Would be great to be able to modify the gallery shortcode to allow this line break!


  23. I am working on a site in WordPress version 3.3.1. I totally new to all of this, but I wondered if your fix would work for this version of WordPress as well? Hard to believe I’ve just spent all afternoon on such a simple thing. Thank you.

  24. This will no longer work with WordPress 3.4, this version finally supports simple HTML-formatting in the captions. This is nice, but brings some problems:
    I have to comment out the two add_shortcode lines in the code above and use for lineshift in image captions posted with the new version.
    The problem is that my old pipe characters (|) which made line shifts no longer work and I will have to replace all these with s manually. Not a small undertaking …
    Does anyone have a workaround?

  25. Hi Terje,
    I haven’t looked at WP 3.4 yet, other than knowing HTML captions are a reality.

    Please know this suggestion HAS NO WARRANTY AT ALL, if it completely trashes your site, you have been warned!

    (In other words, do a full site backup first, before trying 😉

    Given that the | is not a normal character used in most sites, you might be able to install the handy extension Search and Replace

    Once installed, you could try doing a Search / Replace on your site content, searching for the | and replacing it with

    I have a site I would try it on, but I just don’t have time right now. So, if you’re feeling brave, please let us know!

    Best of luck.

  26. Thank you! This (almost) worked.
    Be aware, though, that a double lineshift now demands a blank space between the shifts, e.g.   to work.

Comments are closed.