AMP Debugging Workflow

The AMP Plugin for WordPress targets several user segments either directly or indirectly. Specifically:

  • Developers: These are the folks developing themes and plugins in the WordPress ecosystems. For them the plugin is a tool aimed at exposing the greatest amount of information in the most “digestible” way to guide them through the process of making their plugins and themes AMP compatible.
  • Implementers: These are the folks who are who may be, in some cases, less technical than developers but are responsible for setting up full WordPress sites, with the proper combination of plugins and themes to serve the needs of specific publishers/site owners.
  • Site Owners: These are the folks that are usually referred to as publishers, content creators, etc.; that is, the people that more often than not are not technical but are responsible for the content of their sites.

This document describes the workflow for users in the developers category.  This “user demographics” is a key segment of the users of the AMP plugin because the objective of ubiquitous availability of AMP experiences in the WordPress ecosystem depends squarely on the ability of WordPress developers to create plugins, themes, and technological integrations (e.g. payment flows, identity management, etc.) with full AMP compatibility. The official AMP plugin for WordPress has been designed to serve as a key enabling component to put at the fingertips of developers the tools and information they need to make this happen.

Making a Theme AMP Compatible

The effectiveness of AMP is not only that it makes web pages very fast, but that it does so in a way that can be validated, which in turn makes the performance of AMP pages predictable. The AMP validator checks the validity of AMP pages and reports all the errors in a clear way. The AMP plugin for WordPress makes the power of the AMP validator available to WordPress developers by leveraging the AMP validator rules and exposing any encountered errors in a clear way, with specific information about what the culprit elements are, and plausibly sanitizing (removing) them; more on this in a bit.

To explain the AMP debugging workflow enabled by the plugin, we consider the case of WordPress developers and/or implementers, who have developed beautiful themes. They want to make those themes fully AMP compatible. To achieve this, they need fundamentally the following things:

  1. Identify which AMP validation rules are being violated, if any
  2. Determine contextual information about the validation errors:
  3. Identify which parts of the theme are causing AMP incompatibilities; e.g. which components are injecting custom JS? Is it a plugin? Is it my theme? Is it a Custom HTML block? Or, by how much is the CSS weight exceeding the maximum allowed?
  4. Implement AMP-valid mechanisms that provide the functionality or look-and-feel aspects that would be lost if the AMP incompatibilities be removed

The AMP plugin for WordPress provides functionality to support developers in their journey through these steps. Using these capabilities, you can tackle the task of making your theme AMP compatible. And, the same approach applies when working with plugins, or specific technological integrations (e.g. payment flows, identity management, etc.).

To Sanitize or not to Sanitize

The term “sanitization” usually refers to the process of removing parts of a document for a given purpose, often related to security measures. WordPress itself provides many sanitization functions. In the context of helping developers making their products AMP compatible, the plugin performs the following sanitization actions:

  • If configured to do automatic sanitization, the plugin removes (sanitizes) the offending elements causing a given validation error, preventing it from invalidating the associated page. This does not mean the plugin is fixing the corresponding functionality or visual aspects of the site that might be affected because of sanitizing the error.
  • If configured to do manual sanitization, the plugin does not remove any offending markup, letting the associated page to remain as not valid AMP. This does not mean that invalid AMP will be served, as the plugin will ensure that is not the case.

The actions the plugin can take (to sanitize or not to sanitize) can be controlled by users directly, either at configuration time, or during the process of “AMP-debugging” their site. Specifically, developers can engage with validation errors in the following ways:

  • If the plugin is configured to perform automatic sanitization, any newly identified validation error is classified as “New Accepted” and the offending elements are removed
  • If the plugin is configured to not perform automatic sanitization, any newly identified validation error is classified as “New Rejected” and the URLs with the error will display as non-AMP
  • Users can then toggle the status of errors with the goal of isolating the consequences of these errors in terms of either functional (e.g. responsive menus) or visual (e.g. excessive CSS) discrepancies. Specifically, they can:
    • Accept the sanitization action taken by the plugin; that is, let the plugin remove the offending element causing a given validation error, effectively preventing that error to cause the associated page to be AMP-invalid
      • If the error status was “New Accepted”, it changes to “Accepted”
      • If the error status was “New Rejected”, it changes to “Accepted”
    • Reject the sanitization action taken by the plugin; that is, do not let the plugin remove the offending component, effectively preventing the page from being served as valid AMP content
      • If the error status was “New Accepted”, it changes to “Rejected”
      • If the error status was “New Rejected”, it changes to “Rejected”

The following error status diagram captures the states validation errors can be:

Transitional Mode (formerly ‘Paired’) vs. Standard Mode (formerly ‘Native’)

The fact that the existence of a validation error in a given page indicates that there is a functional or visual piece in the given page/URL (due to a theme, plugin, or any other source) which is not allowed in AMP. If the component causing the validation error is removed, the resulting page will be AMP valid, but the corresponding functionality or visual aspect will not be present.
Accepting a sanitization action by the plugin does not mean the error is “fixed”, unless the corresponding functionality or visual feature is not really used/needed in the site. Similarly, rejecting a sanitization action does not mean that the site will serve “dirty” AMP content, or that the error will show up in the AMP errors section of Search Console. Instead, the behavior of the plugin is as follows:

  • In Transitional Mode, if there are validation errors (not sanitized), the plugin will redirect the given URL to the corresponding non-AMP version
  • In Standard Mode, the html[amp] attribute is removed from the document to prevent the Google bot from parsing the document as AMP and then having validation errors reported in Search Console, which should be reported directly in the WordPress context

Each operational mode has two plausible states with respect to serving or not serving AMP content:

  • In Transitional Mode (formerly ‘Paired’), the alternatives are: serving valid AMP and non-AMP, or serving non-AMP only; that is, there can be one or two versions of the content.
  • In Standard mode (formerly ‘Native’), the alternatives are: serving AMP or only a non-AMP document that uses AMP components; that is, there can be only one version of the content.
  • In both modes, a developer can:
    • Decide which templates will never be served as AMP
    • Opt-out of AMP on a per-post/page level.

By providing this functionality, the plugin enables users to progressively enhance their sites in different ways. A developer could, for example:

  • Start with a non-AMP site
  • Activate the AMP plugin and configure it in Transitional mode (formerly ‘Paired’)
  • AMP-debug all content (see next Section)
  • The URLS that are made fully AMP-valid, will be served as both AMP, and non-AMP
  • The URLs that remain with errors, will be served as non-AMP only
  • Furthermore, for URLs that have errors which cannot be accepted, a user may decide to disable AMP for the entire template or for the specific post/page, effectively preventing the AMP version from ever being served

Or, alternatively:

  • Start with a non-AMP site
  • Activate the AMP plugin and configure it in Standard Mode (formerly ‘Native’)
  • AMP-debug all content (see next Section)
  • The URLs that are made fully AMP-valid, will be served as only as AMP
  • The URLs that remain with errors, will be served only as non-AMP documents which make use of AMP components.
  • Furthermore, for URLs that have errors which cannot be accepted, a user may decide to disable AMP for the entire template or for the specific post/page, effectively preventing the plugin from post-processing them

Let’s see next how to go about AMP-debugging our theme.

Functional/Visual Isolation

From the perspective of a WordPress developer, detecting specific AMP validation errors is just part of the journey towards all-AMP experiences; a necessary but not sufficient condition to solve AMP compatibility issues. The second part is to isolate the functional or visual consequences of removing the culprit of a given AMP validation error:

  • Is there a loss of functional parity?
  • Is there degradation of visual quality?
  • Is the element removal detrimental to the user experience?

Answering these questions is often non-trivial. The AMP debugging workflow described below helps developers to isolate the functional or visual part of their site causing a given AMP validation error.

Debugging Workflow

The Transitional mode (formerly ‘Paired’) plays the important role of enabling developers to start with a non-AMP site and then move progressively towards a Standard mode (formerly ‘Native’) as they systematically go about fixing the validation errors they may have in their product. The AMP debugging workflow described below sheds a light on the path developers traverse from a not fully AMP-compatible site to a native AMP site.

The debugging workflow to make a theme fully AMP compatible is the following:

  • The theme has been tested and it works well even when Javascript is disabled because the theme has functional fallbacks when JavaScript is disabled in the browser
  • The developer installs and activates the theme in their site
  • The developer installs and activates the AMP plugin
  • The theme has functionality that depends on custom JS and has certain CSS components disallowed in AMP, causing AMP validation errors
  • The AMP plugin provides the developer with lots of information about such violations
    • An error index, which can be faceted by error type and by URL
    • An invalid URLs index
  • The developer selects a given Invalid URL to analyze the existing validation errors
  • The developer ensures that all errors are in the New Rejected or Rejected status
    • If auto-accepting sanitization is not enabled, all new errors are in the New Rejected status to start with
    • If auto-accepting sanitization is enabled, all new errors are in the New Accepted status, and the developer must switch their status to Rejected
  • The developer clicks on Preview to and sees the functional and behavior characteristics of the page without any sanitization performed
  • For each error in the list, the developer does the following:
    • Accept the error
    • Use the preview functionality to carefully analyze all the functional and visual details of the corresponding page
    • If no functional or visual disparities are detected, the error can be safely sanitized, and the plugin action can remain accepted
    • If there are functional/visual disparities, the developer has two options:
      • If the discrepancy is not really a problem since it is not detrimental to the user experience
        • The plugin action can remain accepted
      • If the discrepancy is actually critical to the user experience
        • Reject the plugin action, effectively leaving the functionality/visual characteristics intact
        • Fix the issue by providing an implementation that provides the same functional/visual behavior in an AMP-compatible way
    • Go to the next error
  • After all errors have been fixed, the particular template is fully AMP-compatible, and it is ready to be used in either Transitional mode (formerly ‘Paired’) or Standard mode (formerly ‘Native’)
  • Any given template/content type with remaining rejected errors will not be served as AMP
    • In Transitional mode (formerly ‘Paired’), the URL will be redirected to the non-AMP URL
    • In Standard mode (formerly ‘Native’), the URL is not “defined” as an AMP document (i.e. html[amp] is not set), even though it contains AMP components

Progressive Web Development

The AMP-debugging workflow above is intended to enable WordPress developers to advance towards the complete AMPlification of their products in a progressive way. Such a progressive web development approach is further enabled by two features of the AMP plugin:

  • Automatic redirection of invalid AMP to non-AMP (canonical) version. This means that no invalid AMP Pages will be ever served, saving developers and site owners from the sour experience of publishing AMP content just to find themselves being yelled at by Search Console telling them how errors their AMP implementations are triggering. Preventing this from happening preserved developers trust, and enables them to achieve their goals progressively.
  • Conditional template selection. The AMP plugin provides developers with the ability to select which components in their template hierarchy they want to be served in AMP and which not. This capability is available to either the Transitional (formerly ‘Paired’) or Standard (formerly ‘Native’) operational modes. For example, one may decide to have the singular templates (eg. posts and pages) served as AMP, and all the remaining ones served as non-AMP. This flexibility allows developers to focus their attention and efforts to specific parts of their site and expand the radius of their work progressively
  • Selective AMP Opt-out. AMP can be disabled on an individual post basis

The ideal end of this journey is that a given site is configured to be in Transitional mode (formerly ‘Paired’) but there are no validation errors at all. This would indicate one of two things:

  • There are components in the non-AMP version that the developer could not, or did not want to solve. In such a case, the developer can either accept the functional/visual differences, and have two high quality representations of their content for a given template, or reject the discrepancy and serve the content only as non-AMP.
  • The AMP and non-AMP versions of the site are identical, with no functional or visual discrepancy at all. This could be because the removal of offending elements did not really play a role in the UX of the given content template (e.g. unused <script> tag), or the developer isolated the discrepancy and provided an AMP-equivalent implementation. In this case the Transitional mode (formerly ‘Paired’) are identical and therefore this mode would not be actually needed.


The role of the AMP Plugin for WordPress is to serve as an enabler of ubiquitous AMP experiences in the WordPress ecosystem. For developers specifically, the plugin represents a debugging tool which:

  • Helps them identify the existence of validation errors and provides them with a great deal of detail about where the culprits are in their code.
  • Enables them to isolate errors to facilitate the process of actually fixing them and achieving the ultimate goal of visual and functional parity
    Provides automated AMP-compatibility functionality encompassing transcoding, CSS tree-shaking, Gutenberg integration, and much more
    Enables them to go from no-AMP, to high-fidelity Transitional mode (formerly ‘Paired’) and/or Standard mode (formerly ‘Native’) AMP

The debugging workflow described in this document encompasses all the pieces that allow the plugin to serve its purpose and enables developers to succeed in their mission.