WordPress SEO Plugin Theme Integration Guide

Theme authors come in two different shapes and sizes: those who integrate SEO “functionality” into their themes and those who don’t. If you’re in the camp of integrating SEO functionality into your theme, you’ve got yet another choice to make: do you “yield” for site owners that have an SEO plugin installed, disabling your own SEO functionality or do you deny them that choice.

For those who do decide to yield and for those who do not integrate SEO functionality into their theme, this is the guide to follow on how to make sure your theme works with all the major SEO plugins and more in particular, my WordPress SEO plugin.

  1. Basics
  2. Head elements
    1. Titles
    2. Meta's
    3. Link items
  3. Body elements
    1. Breadcrumbs
    2. Other body elements
  4. Is your WordPress SEO plugin active?

Basics

Whether or not your theme is in the WordPress.org repository, you should strive to meet their Theme Review guidelines. With the theme check plugin you can simply check whether that’s the case for most of the technical aspects. This makes sure you have all the necessary hooks for plugins to do their work. If any of those fail, fix them before even looking at the stuff below.

Titles

The most common issue with SEO plugins and WordPress themes is with titles: theme authors have a tendency to hardcode (sections of) titles into their themes, which results in hard to fix behavior, which I recently discussed here and hasn’t been fixed in WordPress core yet. In short, your title should be not even a tiny bit longer than this:

<title><?php wp_title(''); ?></title>

If you decide to embed SEO functionality in your theme, you should then put a filter function on to that wp_title functionality just like a plugin would. This allows you to “unhook” that filter when an SEO plugin is active.

Meta’s

Meta tags come in a vast amount of shapes and sizes, but there are only a few that “matter”. There are the meta description, the meta keywords (on which I have a strong opinion too) and the meta robots tag. In my opinion, your theme should never embed any of these meta tags, but, if you decide to embed SEO functionality into your theme, write functions for these things and hook them on to the wp_head action.

Be very, very sure to allow for site owners to fully disable any meta functionality you write. I regularly, read: daily, advise people to change themes when their theme has a lot of SEO stuff embedded that is just plain wrong or collides with other plugins. Make no mistake: a portion of your users, probably a large portion of your users, cares about their SEO. Getting it wrong is worse then not doing anything, so if I were a theme author I’d most definitely opt for the latter.

There are a lot of <link> items that matter for SEO these days. There are rel=canonical, rel=next and rel=prev and a few more. WordPress does rel=canonical on single posts and pages but nowhere else yet, though a patch for core is ready to make WordPress add rel=canonical in more cases, but your theme should not do any of these. You’re, to be honest, bound to get them wrong.

If you do decide to add them, do it in the same fashion as meta elements: hook them on to wp_head and make sure site owners can disable the functionality.

Body elements

While the above points make integration for any SEO plugin easier, this point is more specific for my own WordPress SEO plugin. Integration of my breadcrumbs is quite easy, use something like the following code:

if ( function_exists('yoast_breadcrumb') ) {
   yoast_breadcrumb('<div id="breadcrumbs">','</div>');
}

This code will not display anything unless the breadcrumbs feature of my SEO plugin is enabled.

Breadcrumbs Variables

This breadcrumb path takes the following 3 variables:

$prefix
The code that your breadcrumb should be prefixed with. Default to an empty string.

$suffix
The code that should be added on the back of your breadcrumb. Default to an empty string.

$display
If set to false, will return the breadcrumb path instead of echo-ing it. Defaults to true.

Other body elements

You should take note of my guides on HTML heading structure and HTML Sitemaps. While my SEO plugin doesn’t “interfere” with those, it’s good practice to make them optimal. You should also read my WordPress SEO Theme Guidelines to make sure you’re doing all the other necessary things.

Is your WordPress SEO plugin active?

You should check whether a constant named WPSEO_VERSION is defined, preferably like this:

if ( defined('WPSEO_VERSION') ) {
// Disable your SEO stuff
}

Tags: , ,


Yoast.com runs on the Genesis Framework

Genesis theme frameworkThe Genesis Framework empowers you to quickly and easily build incredible websites with WordPress. Whether you're a novice or advanced developer, Genesis provides you with the secure and search-engine-optimized foundation that takes WordPress to places you never thought it could go.

Read our Genesis review or get Genesis now!

43 Responses

  1. JackBy Jack on 1 January, 2012

    It’s working, but I should deactivate All In One SEO Pack before.

  2. Jitendra KumarBy Jitendra Kumar on 1 January, 2012

    Thanks for sharing this information. It will be of great help for theme developers to ensure compatibility.

  3. Ben FittsBy Ben Fitts on 2 January, 2012

    I’m more interested in a list of themes that play nicely with your plugins. How come such a list is so hard to find?

    • Hubert Sawyers IIIBy Hubert Sawyers III on 2 January, 2012

      I am with this guy. I am a fan of your plugins, Joost. I would love some insight on this as I would switch to themes that vibe with your ideology.

      • SteveBy Steve on 5 January, 2012

        I am with both of these guy’s. It would be nice. Or to include work-a-rounds in some situations.
        Thanks, Steve

        • Joost de ValkBy Joost de Valk on 5 January, 2012

          Genesis and Woothemes themes work nicely, I’m busy working on a larger list.

          • GarryBy Garry on 5 January, 2012

            Just another vote. An actual list of known themes would be nice. In particular – “Thesis”

    • MarceloBy Marcelo on 6 January, 2012

      Also some best selling Themeforest themes would be great.

  4. KellyBy Kelly on 2 January, 2012

    Superb plugin. I just got rid of another SEO plugin I didn’t find too user friendly and this one allowed me to scrap a couple of other plugins as well. This post helped for integration but is there a general walkthough for all of the settings?

  5. NeelBy Neel on 2 January, 2012

    as you said you have to remove all filters applied to wp_title() function.

    can you show me code to add inside functions.php to remove all filters applied to wp_title() function.

  6. JacobBy Jacob on 2 January, 2012

    Any news regarding Thesis and WordPress SEO?

    • SteveBy Steve on 5 January, 2012

      I would like to know about Thesis also?
      I know you have had issues in the past with Thesis, but with Thesis 2.0 being released sometime ??? will there be any problems with it and your SEO plugin?

      I have Thesis and Genesis and have been trying to decide who to put all my effort into.
      Thanks for all your hard work Joost, Good job!
      Steve

      • Joost de ValkBy Joost de Valk on 5 January, 2012

        Thesis has a history of not complying with WordPress standards. When possible I make changes to work around those but it’ll never be the best supported theme… I’d change to Genesis if I were you.

        • Diego SEOBy Diego SEO on 14 January, 2012

          I have been informed that Genesis does not comply with standards in regards of custom post types. Hence is not supported by some Plugin developers.

          Obviously this is extremely disappointing to me since I have a license and was panning to build some sites using this framework.

          Any opinion?

  7. Jim GaudetBy Jim Gaudet on 2 January, 2012

    Quick ? for you, does the breadcrumbs portion of your plugin add microdata? Like this;

    http://schema.org/WebPage

    • Joost de ValkBy Joost de Valk on 2 January, 2012

      Nope not yet, but I think I’ll add it soon.

      • Jim GaudetBy Jim Gaudet on 2 January, 2012

        Wow, that was fast. Good to know as I am in the middle of creating a theme (e-commerce) and the microsdata is a big part, but separate from the WebPage stuff..

        Thanks!

      • JeffBy Jeff on 2 January, 2012

        +1 for adding Microdata support. This would be icing on the cake of an already awesome plugin (and allow us to switch from NavXT).

      • Dave DoolinBy Dave Doolin on 5 January, 2012

        +1 for breadcrumb schema, thank you.

  8. PhilippeBy Philippe on 2 January, 2012

    Great plugin, thank you !
    Your breadcrumbs work well, but there’s something I haven’t managed to do : If you setup taxonomies to be included in the breadcrumb, and if you have several levels of custom taxonomy, only the top levels is listed. How can I get all levels to be included ?
    example : Home > Video >Films > Thrillers > Pulp Fiction
    and not just : Home > Video > Films > Pulp Fiction
    (where Video is a custom post type, Films a taxonomy level 1, and Thrillers a sub level of Film)

  9. akhilBy akhil on 3 January, 2012

    A fantastic plugin of totally free…Yoast team really Rockz….

  10. Rolands UmbrovskisBy Rolands Umbrovskis on 3 January, 2012

    Since clients sometimes are deactivating plugins, better solution, that I implement for title is

    |

    where wp_title(' | ', true, 'right'); ?> | <?php bloginfo('description'); depends on individual wish :)

  11. DrLightmanBy DrLightman on 5 January, 2012

    Hi, I’m sorry that this is kinda off-topic here but the proper post has been shutdown to new comments…

    http://yoast.com/disable-update-nag/

    I just wanted to point out that that code doesn’t work for me on WordPress 3.1.2 and I guess greater.

    Could you reopen so maybe someone could point out solutions and updates?

    Thank you.

  12. Mike OtgaarBy Mike Otgaar on 5 January, 2012

    I am not a fan of themes with built in SEO tools, so fully agree theme developers should provide a simple way to disable this feature.

    Now I just need to persuade my latest client with a Thesis Theme site to allow me to replace the built in SEO tools with the Yoast SEO plugin. No doubt that will be a hard persuade – one of the reasons he purchased the theme was for the SEO function.

    Looking at the theme settings this will also be a challenge with no way to disable the thing from the theme admin page.

    I am using WordPress SEO by Yoast on 2 of my own WordPress Sites – very satisfied.

  13. Alan LewingerBy Alan Lewinger on 5 January, 2012

    We are using your plug-in and have found it easy to use and understand and most importantly effective.

  14. StephenBy Stephen on 5 January, 2012

    I’m curious what your opinion about using the meta keywords option is? Use it ? Don’t use it?

  15. jarretBy jarret on 5 January, 2012

    Joost, I had been a happy user of another free WordPress SEO–plugin, SEO Ultimate. It has some nice modules such as the deeplink juggernaut, redirection, and Rich Snippet Creator.

    However, and that’s a BIG however, I noticed a very substantial problem while using SEO Ultimate. On my multi-author blog (200+ authors), I hadn’t noindexed the author archives because I wanted them to show up in search. I had incorrectly assumed that the rel canonical features of SEO ultimate would prevent indexing of subpages of the archives. After finally checking, it didn’t. It was allowing a massive amount of dup content getting indexed.

    Long story short, I recently switched to your SEO plugin and problem solved.

    Another funny story, but of all the Google Plus author instructions (to have author bios show up in search), your instructions in a previous post were the ONLY ones I came across that a) made sense b) actually worked. Google should have hired you to write the instructions because theirs were missing some steps (rel=me tag).

    thanks again!

  16. DavidBy David on 5 January, 2012

    On the subject of themes that provide SEO options and the choice to disable them in favour of SEO plugins, I know Catalyst Theme is one such, with an SEO “Kill” switch included to ensure the theme’s own options are disabled in favour of any SEO plugin that may be installed (although I believe it will automatically recognise the most popular SEO plugins anyway)……

  17. OliBy Oli on 5 January, 2012

    I am very much opposed to having ‘SEO integrated’ themes. The way a theme should be SEO friendly is by being as code light and well structured as possible. With so many great SEO plugins out there, themes simply don’t need to include their own SEO modifiers (because they are not always that good).

  18. MarcBy Marc on 6 January, 2012

    Joost you write,

    “Meta tags come in a vast amount of shapes and sizes, but there are only a few that “matter”. There are the meta description, the meta keywords … and the meta robots tag.”

    I have to ask, in what way do the meta keywords matter?

  19. WarrenBy Warren on 6 January, 2012

    Thanks for the guide. All great info. About to attempt my first SEO theme and have been reading all the articles I can find. This one helps a lot with stuff others don’t seem to mention.

  20. David JohnsonBy David Johnson on 9 January, 2012

    I have a Genesis theme. Is there a reason why I would not want to use the Genesis SEO? I see that if I install the WP SEO plugin, the Genesis SEO becomes disabled. What advantage does one have over the other?

  21. Lindsey HightowerBy Lindsey Hightower on 14 January, 2012

    I have been trying to get a handle on this SEO thing,and every time I read a post like this I understand SEO a little better,and yes I use your SEO plug in,because it seems to work the best.

  22. IljaBy Ilja on 18 January, 2012

    Hi Joost,

    I love the plugin. using it on all my sites. I was wondering, is there any way to make the title unique too such as the canonical url part. I am asking this because i use wordpress and datafeeders for affiliate marketing and the only part that is hard to grab, is the titles within datafeeds. A lot of the merchants use duplicate titles for their products. Even though these products differ from each other. a canonical title will help a little against duplicate content ( titles ). Doing this by hand is a lot of work. I know not everyone likes affiliate marketing and pumping sites with content. But hey this is what the market is asking for.

    Thanks.

  23. VincentBy Vincent on 19 January, 2012

    Nice post Joost and thanks for sharing. It is something we are faced with on various projects where the site owners have other SEO plug-ins installed. Generally on any project my first port of call would to be use SEO best practises within the framework of the code. Lately we seem to be working with clients coming in with WordPress sites and yes – preinstalled SEO plugins that either do not play well with other plugins or only give half the functionality needed for good SEO.
    For the past 10 months I have been a proponent of using your plug-in that appears to tick a lot of the major boxes that are needed for SEO. Thanks for putting this up as it is a good guidelines for getting themes to be a bit search friendlier.

  24. Chris BlackwellBy Chris Blackwell on 20 January, 2012

    This is how I think themes should implement the in the header file:

    <?php if ( defined('WPSEO_VERSION') ) : ?>
    		<title><?php wp_title(''); ?></title>
    	<?php else : ?>
    		<?php if(is_front_page() || is_home()) : ?>
    			<title><?php bloginfo('name'); ?></title>
    		<?php else : ?>
    			<title><?php wp_title(''); ?> - <?php bloginfo('name'); ?></title>
    		<?php endif; ?>
    <?php endif; ?>
  25. Tom eaglesBy Tom eagles on 21 January, 2012

    Dear Joast,

    thanks for an amazing plugin, I enabled Breadcrumbs on my site and it works wonderfully however it keeps adding the domain title to the start of each breadcrumb. like Home / Jazykový servis Brno – Jazykové Servisy / Jazykový Servis Brno – Překlady a tlumočení is there anyway to remove the part?

    best regards

    tom

  26. Garry KewishBy Garry Kewish on 24 January, 2012

    Hi Joast,

    Love your plugins and you commitment to professionalism. How much testing have you done with the WP Twenty Eleven 1.3 Theme because i am having issues with the SEO plugin and just want to save time knowing that you have tested this and you know that if functions without issue with this theme running both your SEO and Google Analytics plugins. Also do you have any step by step or detailed videos that walk people through the installation and configuration of the SEO and Google Analytics plugins

    Thank again for such great software and your ongoing support to users such as myself

    Garry

    • Joost de ValkBy Joost de Valk on 24 January, 2012

      Twenty Eleven has one of the worst title functions ever, my best advice is to follow the instruction on the SEO -> Titles page and replace the code within the <title> tags.

  27. matt woodBy matt wood on 29 January, 2012

    Just installed this SEO plugin on my website and now not a single product works or displays.
    I am new to this so having activated it, i deactivated it to see if things went back to normal but no.
    So… reactivated it to see where the problem was and now not even the categories work!
    This is driving me MAD, so would arrpeciate some help if anyone knows what needs to be done or knows why this is happening…
    help really appreciated.

  28. NiallBy Niall on 31 January, 2012

    Once again, an extremely useful article. I much prefer to integrate plugins into a site I give to a client rather than install it separately. The only issue may be if you upgrade WordPress, the integrated plugin may stop working; is that right or am I being a noob lol? ;-)