Yoast SEO: announcing breaking API Changes

As we announced a while back, we’re working on real time content analysis functionality for Yoast SEO. While we wanted to preserve backwards compatibility, we’ve come to the conclusion that we won’t be able to for some filters. This means that some themes and plugins, who integrate with our page analysis functionality, will need to be updated. We will be releasing this update on November 2nd, 2015, so get ready!

Warning upfront: this post is geekier than the average post on yoast.com and doesn’t contain tips for your site.

From serverside to your browser

When Yoast SEO ran a page analysis on your content, this was all done on the server, not in your browser. This meant that when you had a plugin that added a block of text, the plugin would need to register with one of our filters and add that text to the analysis. Our move to a real time analysis means that we’re moving the entire analysis to your browser, instead of the server. This will probably make it easier for most of these plugins to interact with our analysis, but they’ll have to make changes.

The filters that will be removed are described in this GitHub issue. The most important filter, that most plugins and themes use, is wpseo_pre_analysis_post_content. If you use that filter, you will need to make changes as that filter is going away entirely.

We’ve devised a JavaScript plugin system, which we’ve described here. Other plugins can register with our plugin and modify the content and a few other variables. It’s important that you know the basic principles we had in mind when building this system so you understand why we did what we did.

Core requirements to the analysis

We want to make our analysis fast. Super fast. The main requirement we have is simple: when you go into the edit post or edit page screen, you usually have one main objective: editing content. Optimizing content, which is what you’d use our plugin for, is a secondary objective. So we want to make sure that A we don’t slow you down in reaching your primary objective and B we’re making the secondary objective accessible as quickly as possible after that.

Because of how a developer will need to “register” his plugin, the user will be able to see which plugin is causing the long load time. Also, if your plugin takes more than 5 seconds to get “ready”, we’ll ignore it.

The second requirement we have is consistency. For both speed and consistency reasons, we only allow synchronous modifications; if you need to fetch data from the server, we suggest you do it only once and cache the result. You can reload data in the background, and then trigger a reloaded event, which will reload the analysis. This makes sure the analysis continues to be real time and the results are consistent.

Register modifications

The modifications system we’ve defined is a lot like filters in WordPress, so you can think of it that way. It all happens purely in JavaScript space though. We’ve documented how these modifications work in the YoastSEO.js repo’s readme. We’ve also included an example plugin in the same readme.


If you have a shortcodes plugin, you need not worry. We will make a plugin ourselves and ship it with the first release that handles all (properly registered) shortcodes. This will actually be an improvement over how we currently handle shortcodes (right now we ignore them).

To sum it up

  • Real time page analysis is coming to Yoast SEO for WordPress on November 2nd.
  • wpseo_pre_analysis_post_content and a few other filters are going away, if you use that filter, update your code.
  • We will have a working beta on September 9th that you can test your code against. We might have it earlier, follow @YoastDev on Twitter for updates. Feel free to tweet your questions there too.
  • Make sure you follow the guidelines above as otherwise it might not work.

Start developing! If you run into issues, feel free to either open an issue on the YoastSEO.js repository or tweet at @YoastDev. We will try to help as best as we can.

This post first appeared as Yoast SEO: announcing breaking API Changes on Yoast. Whoopity Doo!