This page explains the anatomy and structure of an example theme that might be used on VIP Go. It complements the Theme Handbook that apply to regular WordPress theme development. While every client’s themes will have different requirements and constraints, following this general structure will help ensure faster theme reviews and more efficient long term maintenance of your site.
When we create you a new VIP Go site, we will provide a GitHub repository under the wpcomvip GitHub organization. The repository for each VIP Go site has the following directory structure:
- plugins — for your plugins
- themes — for your themes
- vip-config — for custom configuration changes
- languages – for your translations
- images – any shared images for all your sites
- private – for any files which must not be web accessible (e.g. secret keys)
- client-mu-plugins – for plugins that you want automatically load very early during the WordPress load process
Theme Naming #
Themes in the VIP Go environment live in
WP_CONTENT_DIR . '/themes/'. So if your organization is called Acme Kite Co., for example, your theme path might be
If you anticipate setting up multiple themes for your site or if you are a developer working on different themes for different sites, you might need a naming scheme that further distinguishes themes, e.g.
Plugin Locations #
On VIP Go, there is a dedicated plugin directory in the root of the theme’s Git repository. This directory works similarly to
WP_CONTENT_DIR . '/plugins/' in a WordPress.org installation.
The plugins in this directory can be activated and deactivated from the standard Plugins menu in wp-admin. If a plugin is critical for a site to work, they can also be loaded inside the theme’s
function.php file using
wpcom_vip_load_plugin( 'plugin-name' ); // Note this requires a specific naming structure: /plugin-name/plugin-name.php // You can also specify a specific root file: wpcom_vip_load_plugin( '/plugin-name/plugin.php' );
When do these plugins run? #
Sometimes plugins may have dependencies on running before specific hooks. Depending on how the plugin is loaded, it can be run at three different times:
/plugins– Before the
wpcom_vip_load_plugin( 'plugin-name' )– Before the
require_once( get_template_directory() . '/plugins/plugin-name/plugin.php' )– Before the
What about Shared Plugins? #
The Shared Plugins on WordPress.com VIP are not available to load the same way on VIP Go. Instead, these plugins should be added to the Git repository as if it were a custom plugin. Public Git submodules are supported, so it’s possible to add these directly to your Git repository (Example:
Presence of shared plugins in the mu-plugins directory is a legacy feature which should not be relied upon for future development. Existing sites should take any opportunity to add plugins they are loading from the
shared-plugins directory to their
/plugins directory (we are happy to assist with this). The
wpcom_vip_load_plugin function will load a plugin from the
/plugins directory before it references any version in
client-mu-plugins are scripts that are automatically loaded very early in the WordPress bootup process and do not need to be explicitly enabled or disabled. For multisite installs, the plugins are loaded on all sites on the network.
- loaded before the
- loaded in alphabetical order based on the filename.
- only top-level files are loaded (additional files inside folders can be
requiredby top-level files).
Child Themes #
Child theme-ing works the same in this case as child theming on self-hosted WordPress sites. Just add another theme to your Git repository at
/themes. Because the themes on WordPress.com aren’t available in the Git repository, they will need to be added before they can be used as parent themes.
Unlike WordPress.com VIP, there is no required code in the theme’s
/private folder in your repo, if used, will provide access to files that are *not* web accessible, but can be accessed by your theme or plugins. For example, if you place a file at
/private/sites.json you can access that within your them with;
file_get_contents( '/private/sites.json' );
No visitor will be able to access that file at any URL, unless deliberately exposed via the theme or a plugin.
Use Underscores for a head start #
The Underscores project will generate a starter theme that can be used to get a head start on your theme development. It includes lean, well-commented, modern, HTML5 templates, minimal CSS that’s ready for you to build on, and a variety of tools to help you work efficiently in customizing your theme