Way to WordPress 4.7: Starter Content for Themes

starter content

The release of WordPress 4.7 is just around the corner and the Development Team is occupied with adding as many necessary features to it as possible. Today, Helen Hou-Sandi announced that starter content for themes is going to be added to the new version of WordPress.

Although using WordPress is easy, choosing which theme works for you can cause quite a confusion. The gaps between local theme previews, screenshots, and .org previews make it difficult to figure out where to start and what things are going to be like. The starter content is added to resolve just that.

Starter content is a theme-specific selection of content to help showcase a theme to users and serve as a starting point for further setup of new sites. Starter content works better when together with visible edit shortcuts. It allows users to see what content might work best where within a theme. Users are also able to jump to building off of that base without having to initially spend time figuring out what goes where.

Starter content is applied and displayed upon entering the customizer. Changes will not appear on the live site until customizer changes are explicitly saved and published. In WordPress 4.7, this initial view of a theme with starter content will only happen for “fresh sites” – new installs that don’t yet have any posts, pages, widgets, or customizer settings updated. More information here.

How to Use

Themes will define a subset of starter content provided in core using add_theme_support(). You can take a look at how Twenty Seventeen does things in detail. In its setup function hooked to after_setup_theme, a collection of widgets, posts (pages), attachments, options, theme mods, and nav menus registered as the starter content will be seen.


Widget areas are given ID that corresponds to one registered sidebar. The contents of each widget area listed as an array of widget “symbols” that reference core-registered widget configurations. Most of the default widgets like archives, calendar, categories, meta, recent comments, recent posts and search are available. Also, text widgets with business hours and a short prompt for an “about this site” style blurb are available. Themes should place widgets based on what works best in that area – for instance, business info in a footer widget of a business-centric theme, or a nicely styled calendar widget in the sidebar of a blog.Custom widgets can also be registered at the time of starter content registration or later filtered in.

Posts (Pages)

Similarly, posts which can be referenced by symbols are also provided. Currently, all the options in the core set are pages, but the starter content API can support various post types. The symbols for the core-provided pages in WordPress 4.7 are home, about, contact, blog, news, and homepage-section. Posts are also easily customizable, either by overriding specific fields for a predefined item or by defining a new custom one entirely. The available fields are post type, post title, post excerpt, post name (slug), post content, menu order, comment status, thumbnail (featured image ID), and template (page template name).


Due to the sideloading of specified media, attachments have special handling although being post objects. Media must be loaded from within the theme or plugin directory – external URLs are currently not allowed for performance reasons. The location of the media, either as a full file path or relative to the theme root, is indicated in the file array item, and some other post fields are available, with post content mapping to description and post excerpt to caption. Imported attachments can further be used by using their respective array keys as symbols used within double curly braces, e.g. {{featured-image-logo}} as the featured image (thumbnail) for a post.

Nav Menus

Like Attachments, Nav menus are also specially treated post objects. There are essentially two types of nav menu items – custom links, which require a title and url, and object references, which require type, object, and object ID, which can be a {{post}} symbolic reference.

Options and Theme Mods

Options and theme mods have more freeform and merely require a match for a name. Symbolic references to imported items are particularly useful here, such as for the “Page on front” option and Twenty Seventeen’s multi-section homepage as stored in theme mods. Themes hosted on .org will likely be limited to theme mods and a subset of options. So Hou-Sandi encourages all other developers to consider user experience and expectations first.

What Starter Content does for Themes?

Users can understand how WordPress a specific theme fit their needs. Core-provided content helps support a consistent preview experience across themes with high quality localized content. Theme authors are encouraged to select from core-provided content. But this is WordPress, so starter content still has some flexibility, and will continue to mature as a feature over time.

While theme review guidelines are still waiting to be finalized and documented, it is anticipated that themes being submitted to WordPress.org will be expected to select from core-provided content to promote consistency. So that the theme review process doesn’t lengthen. Themes being distributed outside of WordPress.org are not subject to the same review process but Hou-Sandi recommends to consider consistent user experiences primarily in choosing and implementing starter content.

To best align preview experiences in various places, theme previews on .org should also leverage starter content. Hou-Sandi explains she needs helping hands. If you’re interested, make sure you ping @helen in Slack!

What are your thoughts on this new feature? It seems pretty exciting. Let us know your views in the comments below.

Leave a Reply

Your email address will not be published. Required fields are marked *