Theme Guide

This guide is for anyone interested in making the best possible WordPress themes. Each public theme on WordPress.com is tested against these guidelines to ensure the highest quality. This includes security, plugin compatibility, and support for a wide variety of user-generated content.

Escaping

  1. All dynamic data must be escaped with esc_attr() before rendered in an html attribute.
  2. All dynamic urls must be escaped with esc_url().
  3. If dynamic data is rendered as the attribute of a html script element, it must be escaped with esc_js().
  4. SQL queries containing dynamic data must be escaped with $wpdb->prepare().

Internationalization

  1. All user-facing text must be prepared for translation.
  2. Avoid HTML inside strings passed to gettext functions wherever possible.
  3. The output of sprintf() must be escaped in text strings used in attributes.
  4. printf() placeholders must be escaped before included in HTML attributes.
  5. Provide context where appropriate.
  6. Avoid common anti-patterns.

Queries

  1. Raw SQL queries should be avoided. It is better to use a new WP_Query object whenever possible.
  2. Unbounded queries may not be used. Basically this means that the posts_per_page parameter of WP_Query may not be set to -1. Also, the numberposts parameter of get_posts() (and similar functions) must also have a positive value.
  3. Expensive queries should be transient cached.
  4. query_posts() is not allowed. If you need to modify the main query it is best to use the pre_get_posts filter. If you need to retrieve posts in addition to the main query it is best to use a new WP_Query object.
  5. Empty values may not be passed to the post__in argument used to create a new WP_Query object. If you are using a dynamic value that could be empty it is important to check for empty before using the value in the query. Code example.
  6. Term queries should be tested on an installation with 10,000 terms.

Enqueues

  1. All 3rd party, bundled files must be GPL compatible.
  2. Ensure the correct protocol is used for enqueuing 3rd-party files.
  3. Ensure that the approprite hooks are used to enqueue scripts and styles.

Scripts

  1. Use core-bundled scripts if they exist.
  2. Custom scripts should not be minified.
  3. Bundled 3rd party scripts may be minified but must include this information.

Styles

  1. The main stylesheet (style.css) must be enqueued during the wp_enqueue_scripts action.
  2. overflow:hidden should never be used to contain floats. The micro clearfix is a better alternative.
  3. The !important keyword should not be used where specificity would suffice.
  4. When enqueuing a Google font with multiple character sets, conditionally include the sets with gettext.
  5. Style attributes on HTML tags are not permitted.

Plugin Conflicts

The WordPress.com environment is super-charged with an extensive set of plugins that provide functionality that is shared across all themes. To provide our users with the most consistent experience we ask that functionality that duplicates our plugins not be included on the theme level.

  1. Advertising options are handled via WordAds.
  2. Custom color options are handled by the Custom Colors plugin.
  3. Custom fonts options are handled by the Custom Fonts plugin.
  4. Favicons are handled via Blavatar plugin.
  5. HiDPI support for user-provided images
  6. Infinite Scroll is handled by Jetpack.
  7. Open Graph Protocol
  8. Twitter meta tag support
  9. Various widgets

Data Portability

Ensuring that a user’s content does not change when they switch themes is very important. The following features of WordPress core, while awesome in their own right, can cause a user’s content to change or become unreachable if implemented on the theme level.

  1. Public Custom Post Types
  2. Public Custom Taxonomies
  3. Custom Fields AKA Post Meta
  4. Shortcodes

Theme Options

If your theme includes custom options, we strongly suggest that the Customizer be used instead of a custom admin screen. Doing so has many benefits:

  1. Users can immediately see their changes as they adjust the UI.
  2. There is much less code to write.
  3. Built in user interface modules for the most common situations.

In the event that your theme needs to provide a custom options screen in the admin here are the requirements:

  1. Must be a child of the Appearance menu with a title “Theme Options”.
  2. Use of the WordPress Settings API is required.
  3. All options must be stored as a single serialized array.
  4. Default options may not be inserted into the database upon installation or http request.
  5. All values must be sanitized before saved to the database.
  6. Core functionality must be used for any file uploads.

Most, if not all of these requirements are illustrated in this Theme Options Starter File.

Miscellaneous

  1. Full loops must be used in all templates. Just calling the_post() in a template like single.php or page.php is not enough.
  2. The $content_width global must be set correctly.
  3. Visible links to feeds should not appears in themes. We suggest that site owners use the Follow Blog Widget on WordPress.com to allow their visitors to subscribe.

Usability Guidelines

The WordPress.org Theme Unit Test Data is comprised of multiple posts and pages designed to push your theme to the limits. Please download the data and import to your test server. Running your theme through all of the provided tests can help ensure that your theme will be flexible enough to handle a wide variety of actual user data.

Resources