Got a bunch of white lines in your post that you are sure you didn’t put there yourself? Is your content getting wrapped in paragraphs in all the wrong places? Are shortcodes messing up your text or coming all out of whack?
Welcome to auto-formatting hell. Let’s troubleshoot this.
WordPress allows your content to have filters applied to it. In fact, it has some default filters that are automatically applied. The most notorious of these is the wpautop filter. It’s a function that semi-intelligently cleans up your content by wrapping text in paragraphs and placing linebreaks and such. The concept is great because it means that the end-user doesn’t have to worry about applying the right HTML.
Content filters are also heavily used by plugins to modify the rendering of content. You can do all kinds of neat stuff with content filters, like appending or prepending snippets of text to your content, modifying words or stripping links.
The downside is that content filters can also get in the way, especially when you have content that the content filters don’t deal with properly. These issues are really common when you are working with shortcodes, or certain HTML code (for example, HTML5 brought several new elements that aren’t taken into account by most filter functions).
When you bump into issues with unwanted paragraph wrapping or unexpected amounts of line breaks, it is most likely the wpautop filter that is doing the evil work. For those that are technical at heart, checking out the source code to see what wpautop is actually doing is really helpful. For most people, they will look on the googles to find a solution to their formatting ailments. You will likely find advice to disable this filter. You can do that by placing this code in your plugin file or functions.php file of your theme:
remove_filter( "the_content", "wpautop" );
This line removes the default filter that is applied to the content. Since the wpautop filter is applied in other types of content as well, you would have to apply ‘remove_filter’ to those other contexts as well. To remove the filter from the excerpt output for example, you can copy the above line and replace ‘the_content’ with ‘the_excerpt’.
If you don’t like to code, there are a bunch of plugins that do this as well. But there a problems with this approach. The first problem is that we typically don’t want to have the filter removed site wide. Many users quickly find out that the rest the content on the site now looks condensed and ugly. Argh!
One solution some people use is to apply their own modified filter that does much of what wpautop accomplishes but also takes care of the undesirable behaviour. If all you want is to prevent linebreaks from being added you could call wpautop with an additional parameter that prevents this.
remove_filter( "the_content", "wpautop" );
add_filter( "the_content", "your_custom_wpautop", 10 );
function your_custom_wpautop ( $content ){
$content = wpautop( $content, false ); // false parameter disables br insertion
return $content;
}
If you’re dealing with shortcode issues specifically, you could try reordering the timing of the filter so that your shortcode content is processed before the wpautop filter is applied.
remove_filter( "the_content", "wpautop" );
/* shortcodes are processed with priority 11, the default for wpautop is 10, but we change that here to 30 so that it runs after the shortcode has finished processing */
add_filter( "the_content", "wpautop", 30 );
(You can also process your shortcode before wpautop)
These solutions however will do nothing if another plugin or theme function is running wpautop manually and applying its own filter. Removing the ‘wpautop’ filter won’t work in that case. To get around this you have to figure out what the best thing to do actually is. First of all, if you have tried above solutions and you still have extra paragraphs and/or linebreaks, determine whether it’s a theme or plugin adding their own filter. If you think it might be the theme, switch themes, if you think it might be a plugin, deactivate the most likely culprits one by one and check your results.
If you have determined that it is a plugin or theme function there might be an elegant way to disable their filter. You can run through the code to find out what the filter is called and then use the remove_filter function with that filter name (it’s important you match the same priority level that the filter was added with). You could flat out disable the conflicting plugin in question and use another plugin. You could adjust the theme or plugin code manually, but you’ll lose those fixes when you upgrade.
There are two alternative solutions you could apply if you don’t want to remove any existing functionality sitewide. First, you could disable the offending filter on a post by post basis. Or you could roll your own filter that corrects the formatting (which you could also run on a post by post basis).
Corrective Filter Example:
// filter to remove excess linebreaks from the content
function kill_linebreaks( $content ){
$content = str_replace( "<br>", "", $content);
$content = str_replace( "<br />", "", $content);
return $content;
}
function no_linebreaks(){
add_filter("the_content", "kill_linebreaks", 100000); // removes linebreaks after every other filter has finished processing
}
add_shortcode( "no_linebreaks", "no_linebreaks"); // insert this shortcode if you want linebreaks removed from the post in question
To use this solution, just add the shortcode [no_linebreaks] in the posts that need it. You can also run a shortcode that removes the offending filter.
Advanced Debugging Tips
Here are some tips for troubleshooting tricky situations. The filters that are run are stored in a global that you can access. The add_filter function can be found in wp-includes/plugin.php.
global $wp_filter;
var_dump( $wp_filter );
If you are trying to determine if it’s wpautop being run or some modified version with a different function name, a quick and dirty way to check is to edit wpautop (you can find it in /wp-includes/formatting.php) and insert a debugging statement or function. You can also use debug_backtrace() to pinpoint what files are calling wpautop. Just remember the remove your code or restore a saved backup of the file when you are done.