Documentation VIP Go Anatomy of a VIP Go Theme

Anatomy of a VIP Go Theme

Overview #

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

↑ Top ↑

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 /wp-content/themes/acmekites/.

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. /wp-content/themes/acmekites-main/ and /wp-content/themes/acmekites-seasonal/

↑ Top ↑

Plugin Locations #

On VIP Go, there is a dedicated plugin directory in the theme’s Git repository, gitrepo/plugins/.  This directory works similarly to WP_CONTENT_DIR . '/plugins/' in a installation.

The plugins in the gitrepo/plugins/ 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():

wpcom_vip_load_plugin( 'plugin-name' ); // note this requires a specific naming structure: /plugin-name/plugin-name.php

Plugins can also be put inside a dedicated directory inside the theme:


These will not show up on the Plugins menu in wp-admin and must be loaded with:

require_once( get_template_directory() . '/plugins/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:

  • gitrepo/plugins/ – Before the plugins_loaded hook
  • wpcom_vip_load_plugin( 'plugin-name' ) – Before the mu_plugins_loaded hook
  • require_once( get_template_directory() . '/plugins/plugin-name/plugin.php' ) – Before the after_setup_theme hook

↑ Top ↑

What about Shared Plugins? #

The Shared Plugins on 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: Automattic/Co-Authors-Plus).

Presence of shared plugins in our 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 shared-plugins.

↑ Top ↑

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 gitrepo/themes.  Because the themes on aren’t available in the Git repository, they will need to be added before they can be used as parent themes.

↑ Top ↑

functions.php #

Unlike VIP, there is no required code in the theme’s functions.php file.

↑ Top ↑

Using /private #

The /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.

↑ Top ↑

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


Documentation is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.