The trouble with wpautop

Sometimes, I want a bit more control over the layout of my posts or pages. While most things can be done with TinyMCE, writing in plain HTML (if you know it well enough) can often be the easier way. However, there is a special feature in WP which can stand in your way. It is called the wpautop filter and its main purpose is to help you with formatting standard articles.

The filter will auto-detect line- and paragraph breaks in your written content and will insert the appropriate HTML code (specifically, the required <p> and </p> tags). That's fine in almost any situation, but it can lead to XHTML validation errors when you write HTML content outside the WYSIWYG editor, in which case, wpautop may insert <p> tags in places where no such tags are allowed to exist (e.g. it may surround <div> tags with <p> and that's not valid XHTML).

What's a filter anyway?

In WordPress terminology, a filter is a piece of code that can analyze and modify the content of an article, page or comment before it is sent to the visitor. Default filters like wpautop are implemented by WordPress itself, but additional filters can be added by plugins. Many plugins use filters to implement their functionality. For example, if you want to implement a custom [tag], you need to write a piece of code which scans the content for your [tag] and replaces the tags by the stuff you want to insert. Most filters are implemented with pattern matching PHP functions like preg_replace() and while these functions are well optimized and reasonably fast, the more filters need to parse your content, the slower your blog will get.

So, how to remove the wpautop filter?

First, there are multiple plugins to kill the wpautop filter and some of them will give you even more control on how WordPress will format articles by default.

Use a plugin

WPUnformatted gives you fine grained control on a "per post" basis and allows you to disable wpautop and wptexturize filters. The most elegant and flexible solution as it allows you to control exactly when these filters should be skipped.

PS Disable autoformatting is another, somewhat different and even more powerful approach to control the formatting of your articles. As an additional feature, it can modify the behavior of TinyMCE so that the editor will not automatically remove additional line breaks from your content. When enabled, TinyMCE will preserve the formatting and you can then safely use <br /> tags in the HTML editing mode. You can also insert multiple line breaks.

Use a template modification

Use the remove_filter($scope, $filter_name) function in your template. Requires some PHP knowledge on editing template files. The function takes two arguments, the first is the scope which can be "the_content", "the_excerpt" or "comment_text" and the second one is the name of the filter, which must be "wpautop" in our case. The value of $scope tells WP where it should remove the filter and $filter_name tells it which filter should be removed.

Simple Example: remove_filter('the_content', 'wpautop') will stop WP from running the wpautop filter on the article's content. The call to remove_filter() must be placed before WP obtains the content of an article, which within your template is usually done by the the_content() function call.

The Ugly way by editing the source WordPress source code.

Now, this is only recommended if you really know what you are doing and are aware of the possible consequences. You have to edit the file wp-includes/default-filters.php. This file tells WP which filters should be applied to which content types by default. Inside, you will find a code section starting with the comment // Display filters followed by a larger number of add_filter() function calls. Simply remove the filters you don't want to use and you are done.

A word of caution: Like I said, this is ugly and it will remove the filters globally. Your older posts may rely on these filters so removing them may very well cannibalize their formatting and you may lose the line breaks and proper paragraph formatting. Unless you can be 100% sure you won't ever need wpautop filtering, don't do it this way, use a plugin instead. The advantage of this ugly method is that no additional code is required so this will obviously be the most performance-friendly solution. But also the most crude one. You have been warned :)

You also should NOT disable wpautop for comments. Your visitors are used to format comments with line breaks and wpautop is required to format them. If you disable it, all your comments will obtain a very unpleasant look, without any line breaks and paragraph separation.

How to format articles when wpautop is disabled?

When the filter is disabled, you are responsible for all paragraph formatting. Normally, with wpautop enabled, you can simply use the enter key to insert line- or paragraph breaks and wpautop will convert them to the necessary HTML. Without wpautop, you must insert the <p> or <br /> tags when writing an article. If you use TinyMCE, it's simply a matter of using the paragraph alignment buttons (left, center, right, justified) when writing a new paragraph. This should be sufficient, because TinyMCE will add <p> tags with the necessary style attributes.

When you write your articles in HTML, you must add <p> or <br /> tags manually to format your paragraphs.

Pros and cons of removing wpautop

Like always, there are 2 sides of the coin. If you are an advanced users not afraid of using some HTML to format your posts or if you want to write posts or pages with a more complex layout, you can safely disable wpautop and it may save you from some headaches. Remember that you'll then have to care a bit more about the formatting of paragraphs as WP will no longer auto-detect newlines and paragraph breaks. Also remember, old posts you've written before may look strange when you disable wpautop globally. The plugin solution is the best way to handle this, because it gives you flexible control over the availability of the wpautop filter on a "per article" basis.

If you, however, solely rely on the WYSIWYG editor for writing your content, you should not disable the wpautop filter, because there is no need to do so. In most cases, it works fine  and while it can, in certain situations, stand in the way, it will make it much easier to write well formatted standard content, mostly consisting of text paragraphs with the occasional embedded image.