Common sense is good; enough of it is genius

Tag: wordpress (page 1 of 1)

AMP in WordPress, the WordPress Way


This post summarizes a recent talk Jeanny Haliman and myself gave at AMP Conf, 2019:  Enabling first-class AMP experiences on WordPress is one of the ways the AMP Project aims to bring a user-first experience to websites and content on the web. The Official AMP Plugin for WordPress (, Github) integrates AMP content creation seamlessly with standard WordPress content creation workflows. In this talk we describe in detail how the AMP plugin for WordPress works, how to take advantage of it, and showcase some salient success stories of WordPress sites using the plugin in the wild.

Content Management Systems

WordPress is a Content Management System (CMS), which means that it is a software platform that adds layers of abstraction on top of the web to facilitate the creation, management, and publishing of content on the web. It is certainly one of the largest players in the CMS space, with about 33% of the whole web being powered by WordPress sites today.

Building AMP-first WordPress sites on CMS platforms such as WordPress encompasses a spectrum between a fully manual process, where we as developers do all the work, and a fully automatic process, where the platform, with a combination of core functionality and extensions does all the work for us.

The reality of what is feasible today is a balance point somewhere in this spectrum, where a large part of the process can be automated, and there is a part of the process that requires developer intervention. The exact location of this point, is determined by the status of the ecosystem in terms of AMP compatibility, and therefore, as the WordPress ecosystem evolves, the location of that balance point moves towards maximizing automation and minimizing developer interventionThe key enabling technology influencing AMP compatibility in the WordPress ecosystem is the official AMP plugin for WordPress (, Github).

The Official AMP Plugin for WordPress

The Official AMP plugin is an extension to the WordPress platform, which plays three main roles:

  1. It automates large parts of the process, by integrating into the standard content creation mechanisms of WordPress
  2. It provides tools and guidance to support developers on the parts that need to be done manually, and
  3. It acts as a monitor and enforcer to maintain AMP compatibility as sites evolve.

To fulfill these roles the plugin implements four main areas of functionality:

  1. AMP Validator Integration: The plugin internalizes the AMP specification, effectively becoming a WordPress-centric AMP validator
  2. WordPress template rendering integration: In WordPress there are several ways to create content elements, such as embeds, shortcodes, widgets, and blocks which are triggered during what is called Template Rendering. The AMP plugin hooks into these standard content generation mechanisms and generates AMP-compatible content elements instead
  3. Output buffer post-processing: There are parts of the code that WordPress generates that could be also generated in terms of AMP components, but the conversion cannot be done during template rendering. To deal with these cases, the plugin captures the results of the template rendering phase into an output buffer, parses it into a DOM document and performs a set of processing and conversion tasks:
  4. Content Serving: After these processing phases, we end up with generated content that may or may not be AMP valid. Depending on the outcome, the plugin triggers different serving strategies, aimed at minimizing the likelihood of releasing invalid AMP content to the wild

All this functionality is part of the assisted generation capabilities of the plugin; we don’t have to worry about them and we can focus instead on the parts of the process that require developer intervention.

Building AMP-First WordPress Sites

In WordPress, the look and feel of a site is controlled by a collection of template files, which when combined together, form what is called the theme of the site. The AMP plugin can be configured to interact with the theme of a site in three different ways:

Native Mode

In native mode, the plugin essentially integrates AMP as the framework for your WordPress site. It reuses the theme’s templates and styles to render AMP responses. This means that your site is AMP-first and your canonical URLs are AMP!

Depending on the theme and plugins being used, a varying level of development work may be needed. The AMP plugin helps us by doing most of the work automatically, and this part corresponds to the minimum developer intervention needed to reach full AMP compatibility.

There may be cases where it is not possible to get all the components for a given content type to be AMP compatible at a given time. In these cases, you can either opt out of AMP of those content types or you can leverage the plugin Transitional Mode.

Transitional Mode

In transitional mode  (formerly called Paired mode)  the plugin also reuses the active theme’s templates, but it renders AMP and non-AMP responses. Although there are two versions of the content, your site’s theme is used in both cases, and you as a developer have control of what is generated for either case.

This mode is called transitional because it is intended to provide you with a migration path, to progressively expand the AMP compatibility of your content, until you can switch easily to native mode.

There are cases where we may want to provide an AMP experience to our users, but don’t have the resources to carry out the development work needed for the native of transitional modes. In these cases, we can take advantage of the plugin Reader Mode.

Reader Mode

In Reader Mode  (formerly called Reader mode), the plugin generates AMP content using separate simplified templates that are neat and light but may not match the design of the underlying theme of your site. This mode is useful for providing basic AMP experiences, but we don’t actually recommended it because transitioning to AMP-first experiences in WordPress is getting easier and easier.

Now that we understand the different template modes let’s go over the development workflow for building AMP-first sites in WordPress.

Development Workflow

The workflow for developing AMP-first sites in WordPress encompasses three main tasks:

  1. Identify: The first part of the workflow is identifying any validation errors being triggered by components of our site
  2. Contextualize: The second part is Contextualizing those errors, to understand where the offending code or markup elements are coming from; which component of the site injected it?
  3. AMPify: And finally we must AMPify the offending components so that the validation errors can be removed without losing visual or functional parity

The AMP plugin does all the work on identifying and contextualizing validation errors. And it also does quite a bit of the work needed on the AMPification part, by automatically generating AMP-compatible components, or automatically removing offending components (with user consent).

Identifying Errors

This screenshot gives you a glimpse of content creation and editing in WordPress. In the WordPress editor, everything is a block. The blue rectangle here is a Custom HTML block we added to our content. And in that block a piece of code is added which violates AMP rules.

When we update the post, the plugin flags the error, in the context of the block, as well as a clear warning notice on top that alerts about problems in this particular content as well as in other parts of the site.

Contextualizing the error in this case is easy since we have it in front of us. But in WordPress, code can be generated in a variety of ways and keeping track of the sources of specific errors is one of the most difficult parts of AMP development in a CMS such as WordPress. The good news is that the plugin does all the work needed to contextualize errors.

Contextualizing Errors

The plugin hooks its functionality into the content generation mechanisms of WordPress and annotates the generated markup with HTML comments. When a validation error is encountered, the plugin walks the DOM tree back to determine from the HTML comments the source of the error and other contextual information. Each URLs affected by a given validation error is associated with  the same validation error object.

Once the plugin has identified and contextualized existing errors, the question is what to do about them?

Plugin Actions

The plugin can be configured to do one of two things:

  • If configured to do automatic sanitization, the plugin removes the offending markup causing a given validation error, making the associated URL valid AMP. This does not mean the plugin is fixing the corresponding functionality or visual aspects of the site that might be affected because of removing the offending markup.
  • If configured to do manual sanitization, the plugin does not remove any offending markup, letting the associated page 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.

But the ultimate decision about what to do with identified errors is taken by the developer.

Developer Actions

As a developer, you can decide to either:

  • Accept the plugin action, effectively saying “it is ok to remove that invalid markup from my AMP pages” because it is either not really needed, or because you have an AMP valid solution, or
  • Reject the plugin action,  effectively saying “that particular markup element cannot be removed”, because it is key for the experience of my site, and I don’t have an AMP-valid solution for it yet

AMP Plugin Compatibility Tool

The plugin exposes these capabilities via a compatibility tool that puts at the fingertips of  developers all the information gathered on the identification and contextualization of errors. In a nutshell, the compatibility tool exposes:

  • Details about the markup causing the error
  • The source of each error: the theme, a specific plugin, or core
  • The type of error it is: CSS? HTML? JS?
  • And provides the UI for developers to take the action of accepting or rejecting the corresponding sanitization action taken by the plugin

Making a Theme AMP Compatible

At this point you should have a good sense of the capabilities of the plugin and the elements of the workflow for developing AMP-first sites in WordPress. Let’s go now over a simple but real-world example of making a theme AMP compatible.

As we mentioned before, depending on the characteristics of your theme, the level of work required to achieve this would vary. But although this example is not too complex, it will give you a clear sense of the workflow you should follow for making your theme AMP-first.

Starting Point

We start with a theme has been tested and it has functional fallbacks so that it works well when JavaScript is disabled in the browser.

In our example we start with the Twenty Thirteen Core theme, which is a classic, simple WordPress theme, with a site identity section, a hamburger menu, search bar, some content embeds such as YouTube and Twitter, widgets, and features like that. To test this example yourself, get a brand new WordPress install, install the AMP plugin for WordPress, and the Twenty Thirteen Core theme.

Activate the Plugin

The first step is to activate the AMP plugin in our admin screen and configure the plugin to operate in Transitional mode to progressively make the theme AMP-compatible and once we get to full AMP compatibility we can switch to Native mode. We configure it also to not remove automatically any offending markup, because we want to analyze each validation error to understand it and fix it.

Once we Save the configuration, we can see the plugin telling us that there are some validation issues we need to investigate and fix.

The next step is to take a look at the content of our site and see where the validation errors are coming from.

Analyzing a Post

We pick a specific post. Since the plugin is configured in transitional mode, we land on the non-AMP version of the post, which has the functionality we get from the 2013 theme.

We have access to the AMP version of the post from the Admin bar, and when we try to go to the AMP version, the plugin tells us the AMP version is not valid.

We can then go to the compatibility tool to see the errors and all their contextual information. There you can see the errors in red, which means the plugin did not remove the offending markup elements. Notice as well on the right sidebar, that AMP is disabled for this post, which means AMP content will not be served.

We will not dive into analyzing the errors now for the sake of time and space, but we can get you a summary of what is happening. If we look at the source and type columns in the compatibility tool, we see that there are:

  • Two CSS errors having to do with viewport at rules (see CSS error type), introduced by the theme itself.  These CSS errors are easy to fix because the viewport @-rules are actually not needed and can safely be removed.
  • Four JS errors caused by scripts being loaded by WordPress core (e.g. JQuery library, and some other scripts). This scripts inserted by the core platform are usually related to dependencies for scripts introduced by our theme.
  • Two JS errors caused by scripts belonging to the theme itself; these are probably important since they must have functionality specific to this theme

The next step is to isolate the errors, by letting the plugin remove the offending elements, and then look in detail at our theme to see what visual or functional disparities exist, if any.

Isolating Errors

To isolate the effect of individual errors, we mark all errors as “Accepted”, which tells the plugin to remove the offending elements. And then we use the preview functionality, which allows to analyze the effect of the plugin actions without actually applying the changes to the post.

Notice that by doing this we have made the post to be valid AMP, but we need to ensure there is no broken functionality or visual disparities. In this case, we checked the post and found that everything is good, except for the hamburger menu that was broken by the removal of one of the theme JS scripts which provided that functionality.

The next step is to make the fixes in the theme to remove the causes of the errors and implement the functionality of the hamburger menu in a way that is AMP compatible.

Fixing the Errors

In the style.css file, we first remove the CSS viewport at rules that are not needed.

In the functions file of the theme we implement a function to check when AMP content is being requested and use it to wrap the parts of the theme where the JS files are being enqueued and prevent that from happening on AMP responses.

Then we add theme support to tell the plugin to handle the hamburger menu conversion. Most themes include some custom JavaScript to support presenting the nav menu. Since the implementation looks very similar for most themes, we added support in the AMP plugin to provide an AMP compatible implementation. To leverage that functionality:

// Add AMP theme support for responsive navigation menu
        'paired'            => true,
        'nav_menu_toggle'   => array(
	  'nav_container_id'  => 'site-navigation',
	  'nav_container_toggle_class' => 'toggled-on',
	  'menu_button_xpath' => '<xpath to button>',
	  'menu_button_toggle_class'   => 'menu-toggle',

Where we pass the “amp” parameter to the add_theme_support functio, and an array of additional parameters extending AMP support:

  • paired = true”: the plugin is operating in Transitional mode
  • nav_menu_toggle”: gives the plugin information about the hamburger menu markup, so it can provide the corresponding functionality using <amp-bind>

The next step is to verify the fixes.

Verify the Fixes

To verify the fixes, we trigger a recheck of the post in the compatibility tool, and see that all the errors are gone. Finally, we review the functionality of the post and ensure that everything is in order, including the functionality of the hamburger menu.

“Graduating” to Native AMP

At this point the AMP and non-AMP versions of our 2013 theme are identical both in terms of functionality and look-and-feel. Therefore, there is no need to keep both and we can graduate our site to Native Mode. As you can see in the video this is as simple as changing the value of the parameter paired passed to the add_theme_support function from true to false.


In this post we provided a concise yet extensive description of the official AMP plugin for WordPress, with details on its functionality, how its capabilities fit in the developing AMP-first sites in WordPress, and went over a simplified but representative example of how to make a theme AMP compatible.

To learn more about the AMP plugin please check the plugin product site, and follow the development of the project on Github.

AMP in WordPress

If you only have one minute to read this post, here is the gist of it: WordPress users can get a first-class AMP experience without compromising the fidelity of their content or surrendering the flexibility of the WordPress platform. Get a glimpse of what is possible with AMP in WordPress by watching our AMP Conf 2018 talk! If you have a few extra minutes, follow me to the next paragraphs to learn more about the state of AMP in WordPress.

The WordPress Ecosystem

Screen Shot 2018-02-11 at 8.14.19 AM In a nutshell, WordPress is: a Content Management System (CMS) for websites; the largest player in the CMS space with ~59% of market share, powering about ? of the web; and a thriving ecosystem of plugins, themes, hosting providers, agencies, freelancers, all working together on the creation of WordPress-powered content. But when I think about WordPress I think about one thing: there are many users publishing and consuming content via WordPress-powered sites, and all of them should get an awesome UX on the platform.

And since AMP is all about enabling an awesome (fast) User eXperience to all users, in this post we discuss two things: (1) the case for AMP in WordPress; and (2) the state of the art of AMP in the WordPress Ecosystem. Curious? Read on!

Why AMP in WordPress

One of WordPress major virtues is the flexibility of the platform. You can accomplish basically anything you can imagine, as demonstrated by the large and ever expanding ecosystem of plugins available to add functionality and customize your website in a myriad of ways. However, this same virtue can also turn into one of the major challenges of the platform. Even taking into account plugins that are very good (i.e. follow coding/performance best practices and coexist nicely with other site components), the likelihood of having plugins colliding in their interactions (or impacting performance) when jointly activated in a site, is definitely not negligible.

This virtue/challenge duality of the WordPress ecosystem has its parallel in the open-web web publishing ecosystem. In the latter, there is nothing restricting a web developer to hamper the performance of a site by following counterproductive coding practices (e.g. loading scripts synchronously, render-blocking CSS). And even if the developer builds a site impeccably, adding a third-party JS library could spell a performance disaster.

AMP emerged as a response to that reality, bringing forward effective design principles and control mechanisms that enable sites to offer predictable performance. The effectiveness of AMP and its impact on UX is demonstrated by plenty of data and examples in the wild. And WordPress publishers would also benefit greatly from having more control of the UX of their sites. This could be achieved by adopting coding and performance best practices in WordPress development, and integrating AMP with the WordPress ecosystem to make the WordPress platform more performant.

The plugin work for enabling AMP in WordPress described in this post, was pioneered by the AMP Plugin initially developed by Automattic. Subsequently Google and XWP joint the open source development effort to help evolve the plugin significantly. Want to know what is possible with AMP and WordPress nowadays? Let’s see!

The AMP Plugin

The initial goal of the AMP plugin was to enable AMP for VIP sitesIt certainly met its goals for VIP, and it was also adopted at some level by the general WordPress community either directly, or through other plugins built on top of it. In the context of its initial objectives, the main characteristics of the early versions of the AMP plugin make sense:

  • Developer oriented. The plugin provided a minimal set of core abstractions to enable AMP in WordPress, and allowed developers (i.e. agencies, plugin and theme makers) to modify it and extend it to tailor its capabilities to the needs of their individual sites.
  • Pair mode. The plugin adopted a simple-theme approach bypassing the WordPress template hierarchy and generating a separate AMP version of published content based on very basic theme template parts.

These characteristics worked well for sites that have good engineering support to tailor the AMP content to their needs. However, at a larger scale, the adoption of the plugin was more challenging because the baseline capabilities did not offer enough functional and visual parity between the two versions.

Google and Automattic started working together last year with the goal of bringing the AMP plugin to its maximum expression, and enable a rich AMP experience for all WordPress sites. A few months after,  XWP engineering team also joined the project to push for the same goals with the expanded scope of integrating modern web technologies in general into the WordPress ecosystem. And since everything is open source, the WordPress community has also been part of this work through many contributions. In the past few months versions 0.5 and 0.6 of the plugin were released, including bug fixes, expanded support for embeds, support for pages, parity with AMP library specification, better configuration capabilities, and much more. And after these, we have focused on one of our main initial goals; since the beginning we have had our sight set on enabling an organic AMP experience in WordPress; that is, an experience where there is no need for a pair mode (unless applied by choice) because there are no gaps, either functional or visually, between the AMP and non-AMP versions of content published in WordPress. Without such a gap, WordPress publishers are able to publish a single version of their content which is beautiful, feature-rich, all-around WordPress, and runs at the speed of AMP! We call this an all-AMP experience.

An all-AMP UX in WordPress

The aforementioned pair mode approach makes sense when there are functional and visual gaps between the AMP and non-AMP versions of a given content. In such a case the pair mode keeps a “version” of the original content and an AMP’d version of  it. By enhancing the AMP plugin and devising the right mechanisms for theme/plugin integration, we can eliminate these functional and visual gaps an enable WordPress sites to offer a single, all-AMP experience.

Screen-Shot-2018-02-10-at-4.59.38-PM.pngAn all AMP experience in a WordPress site requires: (1) a plugin that enables a seamless integration of AMP into WordPress; (2) a theme that integrates nicely with AMP (adds AMP theme support); and (3) the seamless coexistence of third-party plugins in an all-AMP site.

We have made good progress on the plugin work and by the time you are reading this post, many goodies will be available in version 0.7 of the plugin (release). We have also made progress on defining an approach for building progressive themes; that is, themes built following the latest coding and performance best practices, leveraging as much as possible progressive technologies in the web platform, and integrated seamlessly with the AMP plugin. The result on this work was presented at AMP Conf (video), and a prototype of an AMP-Compatible theme is available, and you can experience it live as well.  And the cherry on top of the cake, is the work by Morten Rand-Hendricksen on the development of a Progressive Theme Boilerplate project, which enables theme developers to go from 0 to starter progressive theme in an easy way. Today, a native AMP experience in WordPress is possible! On the theme side of the story, native AMP support is enabled by:

  • Integrating with the standard WordPress templating system, as opposed to the AMP plugin’s initial paired mode bundled theme for post templates
  • Supporting standard site elements such as the Widget sidebar, native comments, and many others are fully supported
  • Providing opt-in choice for enabling the experience with fine-grain control: the theme works with or without AMP

And on the AMP plugin side of the story, the seamless integration of AMP into the WordPress workflow is enabled by:

  • Supporting all standard/default widgets; non-core widgets will also work, but anything they add which is not AMP-compatible will be stripped. And we encourage the plugin community to work with us on their integration
  • Providing AMP compatibility for all relevant WordPress actions / filters
  • Preventing WordPress from printing  scripts/styles in the header and footer
  • Having an efficient “AMP preprocessor” ensuring AMP validity with maximum fidelity
  • Providing functionality in the AMP preprocessor to identify and flag incompatible plugins at runtime. Besides helping the publisher to keep their AMP content valid, this also will help guiding the community to work with us to make every relevant plugin AMP-compatible
  • Allowing three “use modes”: (1) legacy pair mode, with the pre-0.6 ad hoc post templating system; (2) new (enhanced) pair mode, integrated with the standard WordPress templating system; and (2) AMP Canonical, with a single AMPed version of the content and also integrated with standard templating system.
  • Supporting all default embeds; other embeds are also allowed but the AMP preprocessor may not make them AMP compatible in the best way (i.e. an may be used)

The combination of these features and capabilities allows WordPress publishers to run a pristine WordPress site that is all-AMP! The following screenshot shows a demo of an all-AMP WordPress site; there is no pair mode, and look at the console! AMP-Canonical-WordPess-Demo

The Road Ahead

AMP integration with the WordPress ecosystem has come a long way. But there is still quite a bit of work ahead of us; very exciting work indeed! Some of the main areas currently capturing our focus include:

  • Continue expanding the capabilities and scope of the AMP plugin to fully enable an awesome AMP experience in WordPress at scale, and collaborate with publishers, WordPress users, and the WordPress developer community, to make all relevant plugins/themes AMP-compatible
  • Continue our work on Progressive Themes aimed at defining a systematic approach to building themes that provide AMP support, follow the latest coding and performance best practices, and integrate the latest advances in the web platform.
  • Align our efforts with the evolution of WordPress via contributions and integrations with Gutenberg, the new editing experience which is set to revolutionize content creation in WordPress. This includes supporting Gutenberg blocks, including blocks for AMP Components. For example, we’re looking to augment Gutenberg blocks with AMP-specific attributes, like the layout and media attributes, which  would then inform the AMP preprocessor on how best transform an element into AMP.
  • Contribute our collaboration with the Tide project, to empower WordPress developers and site owners with the ability to choose themes and plugins based on concrete quality metrics
  • Enable the systematic tracking of the performance of the WordPress ecosystem by leveraging extensive datasets and the power of Google’s data processing infrastructure

Advances in the web platform all aim at improving the user experience along different dimensions. AMP design premises focus on the performance of the mobile web and the associated quality of the perceived user experience. With the AMP plugin and a modern approach to building themes, WordPress-powered publishers are able to leverage the performance and ecosystem advantages to be gained from using AMP. There is still quite a bit of work to be done. These are very exciting times to be a web developer, and also a WordPress developer! We are certainly excited as we continue advancing towards our goals and unlock the even greater potential of the WordPress platform. And remember: everything we are working on is open source, including AMP! All the work described in this post is the result of a great collaboration between Automattic, XWP, Google, and the WordPress community. Want to help? Join the effort and participate with your contributions, feedback, and engagement!