WP caption structure

<div style="width: 169px" class="wp-caption alignnone" id="attachment_14">
 <a rel="attachment wp-att-14" href="http://www.whatever.com/attachment/">
 <img width="159" height="300" class="size-medium wp-image-14" title="Lorem ipsum" alt="Lorem ipsum" src="http://www.whatever.com/image.png"/>
 </a>
 <p class="wp-caption-text">Lorem ipsum</p>
</div>

From the above HTML code the whole image content is wrap using a block elements "<div>".

The issue

If the below condition is met it will render the whole document invalid.

1. Image caption is placed inside a paragraph.
2. Wordpress wpautop (default filters) is enabled; wpautop will auto append <p> on raw text content.

Turn it off

Special Constant

Interestingly a simple caption shortcode has a user defined constant. It seem like WP developer has predict that their implementation is highly debatable.

Alternatively you have the options to hardcode the below Constant to disabled the “Auto Caption” features inside wp-config.php.

define('CAPTIONS_OFF',1); // disabled auto image caption

WP Caption shortcode filters

It has filters too, img_caption_shortcode. For advance WP user you can bind this hook to overwrite the default caption template.

Workaround

My workaround involved 1. removing the caption shortcode 2. make a new one. I did this because I don’t like the img_caption_shortcode filters as seem like too much of work.

1. First we recreate/replicate the caption shortcode functions. Named it nwp_caption_shortcode - new wp caption shortcode

   function nwp_caption_shortcode($attr, $content=null){	
   
   	if ( defined('CAPTIONS_OFF') ){
   		// no check for bool its literally meant off/ get off
   		return $content;
   	}
   
   	extract(shortcode_atts(array(
   		'id'	=> '',
   		'align'	=> 'alignnone',
   		'width'	=> '',
   		'caption' => ''
   	), $attr));
   
   	if ( 1 > (int) $width || empty($caption) ){
   		return $content;
   	}
   
   	if ( $id ) $id = 'id="' . $id . '" ';
   
   	$output = '<span ' . $id . 'class="wp-caption ' . $align . '" ';
   	$output .= 'style="width: ' . (10 + (int) $width) . 'px;display:block">';
   	$output .= $content;
   	$output .= '<dfn class="wp-caption-text">' . $caption . '</dfn></span>';
   
   	return apply_filters('nwp_caption_shortcode',$output);
   }
   

   The shortcode functions is pretty much the same, the only different is I used <span> to wrap the image content and <dfn> to hold the caption text.

2. Next create a function to unregister the default caption shortcode.

   function remove_caption_shortcode(){
   	foreach(array('wp_caption','caption') as $tag) {
   		remove_shortcode($tag);
   	}
   }
   

3. Lastly we register all this functions.

   if (version_compare($GLOBALS['wp_version'], '2.6', '>=')){
   	add_action('init','shortcode_init');
   }
   
   function shortcode_init(){
   	add_action('loop_start','remove_caption_shortcode',10);
   	add_action('loop_start','reg_shortcode',11);
   }
   
   function reg_shortcode(){
   	add_shortcode('caption','nwp_caption_shortcode');
   	add_shortcode('wp_caption','nwp_caption_shortcode');
   }

Download