Serving Strategies

The AMP plugin offers three template modes, which determine the kind of AMP experiences a given site can provide:

  • Native AMP mode: In this mode the plugin enables sites to have AMP as the only version of their content. That is, in this mode there are no separate AMP-specific URLs on the site; the entire site will be served as AMP (demo screencast, example site), and there won’t be an ?amp query parameter appended to any URL.
  • Paired AMP-non-AMP mode: In this mode themes can register support for AMP, effectively enabling sites to reuse their theme’s templates and styles in both the AMP and non-AMP content. Site owners have the option of delivering AMP and non AMP experiences with the same look-and-feel, avoiding disrupting the brand experience for the end users. In this mode the ?amp query param is used exclusively for the AMP version.
  • Classic (simple) AMP-non-AMP mode: The classic behavior of earlier versions of the AMP plugin was to serve AMP responses in basic templates (with that blue bar at the top) which are separate from the templates in your active theme. The experience in this case is delivered via in a simplistic manner (i.e. simplified theme layout and contents). In this mode, the URLs for AMP posts normally end in /amp/ whereas for pages they end in ?amp (and in both cases the “amp” slug can be customized to be something else).

Conditional Template Support

An important feature in v1.0 of the plugin is the ability of granularly selecting which templates in the template hierarchy of a site should be served as AMP and which should not. This way, site owners can prioritize the efforts to make their site fully AMP compatible.

Granular Opt-out Support

There may be scenarios where the user experience for a given post content requires the addition of a component that is not AMP compatible. In this case the user has two options:

  • Reject the sanitization actions of the plugin. By doing this the plugin will flag the error and will ensure that the non-AMP version of the post is served (no AMP validation errors will surface in Search Console).
  • Opt-out of AMP for that particular post by simply toggling the “Enable AMP” switch on the post edit screen sidebar

This allows users to select posts that can have specific AMP-incompatible content without disrupting the overall AMP strategy of the site.

Hybrid Modes

The AMP plugin provides the flexibility of combining the described template modes with conditional template support, and granular opt-in for specific pieces of content. These combinations yield two additional modes which can be seen as hybrid modes.

Mixed with Some Content in Paired (AMP/non-AMP) mode

In this mode all content on the site is available in non-AMP mode, and some of the content is also available in paired AMP/non-AMP mode. And the same theme templates are used in all cases.

Mixed with Some AMP-only Content Only and some non-AMP only Content

In this mode, all the content there is only one version of the content, either AMP or non-AMP; that is, the AMP and non-AMP content sets are disjoint.

Configuring Template Modes

As of version 1.0 these options can be configured either programmatically using add_theme_support( ‘amp’ ), or via the plugin’s admin panel.

Via Admin Screen

The screenshot below shows the plugin’s admin panel with the available options for configuring the template mode, validation handling strategy, and template hierarchy selection.

AMP Settings page
AMP Settings page, supported templates

The plugin offers the option of selecting all templates as one to be served as AMP, but users can uncheck the “Serve all templates…” checkbox and pick specific templates from the list of the main templates in the Template Hierarchy to be served as AMP.

Via Programmatic Access

In addition to being able to opt-in to the theme templates you want to serve as AMP via the admin settings screen, you can also programmatically force which templates are enabled and which are disabled.

Classic Mode

The AMP plugin ships with legacy default templates which very simple. The resulting AMP content usually looks nice and clean but very different from the canonical version of the content.  These default templates can be configured via simple options.

Note: the use of this mode is strongly discouraged. It will continue being part of the plugin in the short term, but it will certainly be deprecated in the not too distant future. The good news is that the plugin provides functionality aimed at facilitating migrating to the new paired or native modes.

Paired Mode

The new paired mode can be enabled either via the admin screen, or you programmatically via:

add_theme_support( 'amp', array(
	'paired' => true,
) );

Doing this will make the plugin automatically re-use the main theme templates in the AMP responses when accessed via AMP-specific URLs. It is also possible to supply a template_dir parameter pointing to a different directory from which to pull the AMP templates.

add_theme_support( 'amp', array(
	'template_dir' => 'amp-templates',
) );

This is useful in cases where significant changes to the underlying theme must be made, which are not easily achievable/ facilitated by adding is_amp_endpoint() checks in the main template files.

The recommended approach is to use is_amp_endpoint() in your main templates to output different content for the AMP and non-AMP versions since this reduces duplication. For example:

<button
	class="menu-toggle"
	aria-controls="primary-menu"
	aria-expanded="false"
	<?php if ( is_amp_endpoint() ) : ?>
		on="tap:AMP.setState( { siteNavigationMenuExpanded: ! siteNavigationMenuExpanded } )"
		[aria-expanded]="siteNavigationMenuExpanded ? 'true' : 'false'"
	<?php endif; ?>
>
	<?php esc_html_e( 'Primary Menu', '_s' ); ?>
</button>

Native Mode

Native mode can be configured programmatically in a theme or child theme by adding the following code snippet:

add_theme_support( 'amp', array(
   'paired'       => false, // Force native mode
) );

Or by the same code snippet without any parameters:

add_theme_support( 'amp' );

Conditional Template Support

When adding amp theme support you can do the following to force singular template to be available in AMP and forbid the search results from being in AMP:

add_theme_support( 'amp', array)
      'templates_supported' => array(
               'is_singular' => true,
               'os_search' => false,
      ),
) );

If we do that at the code level, then the corresponding template checkboxes in the admin panel will be disabled. Also, we can programmatically force all templates to be served as AMP:

add_theme_support( 'amp', array(
      'templates_supported' => 'all',
) );

If the plugin is used on a theme which does have the add_theme_support( ‘amp’ ), the template mode radio buttons are disabled in the admin panel.

A notice for built-in AMP support
ParameterTypeDescription
pairedboolean
Flag indicates when paired mode should be used. If absent will default to native unless template_dir is supplied.
template_dirstring
The path to the custom template(s); to be used in paired or native modes
templates_supported‘all’ | array
If ‘all’, every template in the theme will be supported in AMP. If array, then it’s a mapping of supportable template conditions to whether or not AMP is forced
comments_live_listboolean
Whether amp-live-list will be used for comments. On making a comment, this will display the comment without a page refresh. If this parameter isn’t present or is false, the page will refresh on making a comment. This also requires adding markup to the theme (see this wiki page)