How to try out AMP with Drupal

What is AMP, and why should I give it a try?

In “AMPing up Drupal,” Matthew Tift explained what AMP is, and how we worked to create a module, theme and PHP library to use AMP with Drupal. Spoiler alert: AMP stands for Accelerated Mobile Pages, and it’s an open source project developed to make web pages super fast on mobile. It’s particularly geared towards content like articles or informational pages, rather than e-commerce or applications. If you haven’t read Matthew’s article, do so now, as from here on out, I’ll assume you know the basics of AMP.

Lullabot released the Drupal 8 version of the AMP module and theme on February 26, and we are delighted to announce that a Drupal 7 version is now available. These are still beta versions, and we hope to continue improving upon them. We think they’re at a point where it’s worth giving them a try, even if only to test how it works locally or in a feature branch for your site.

I’m going to walk you through how to get started. Setting up your site for AMP takes a few steps, but you get a good deal of control over how your AMP pages look as a result. This walkthrough will explain the process step-by-step, providing a little more context than you might find in the README. For the bold and adventurous, you’re welcome to try this out straight from the Drupal 7 README or the Drupal 8 README! 

After the walkthrough, I’ll share a few thoughts on why I think you should try out AMP.

Setting up AMP with Drupal

The first key thing to understand is that AMP does not replace your entire site. AMP exists to provide a lightning fast way for site visitors to view articles and other content-focused pages.

At its essence, the AMP module provides an AMP view mode for certain content types, which the site can show when the browser requests an AMP version of a page.

On that AMP view mode, you can select AMP field formatters to take care of converting some of your content so they use the proper AMP tags. The AMP PHP library processes raw HTML, like the content in your body field after it has been filtered and had tokens replaced (if you are making use of the Token module). The library attempts to replace HTML content with AMP HTML components. It filters markup it cannot convert out of the final AMP HTML. This helps ensure the validity of content under editorial control, which may have a wide variety of embedded content.

When visiting pages with AMP-enabled content types, if the URL has ‘amp’ in the query string (e.g. my/favorite/page?amp), Drupal will use the AMP view mode and AMP theme selected on the AMP configuration page (admin/config/content/amp). The AMP Theme project provides an AMP Base theme that takes care of converting some of the larger parts of the page into AMP. For Drupal 8, that’s the html.html.twig, page.html.twig and node.html.twig templates; in Drupal 7, html.tpl.php, page.tpl.php, and node.tpl.php. The theme provides a subtheme aptly named the ExAMPle theme that demonstrates how to customize the appearance of AMP pages with custom styles. You could also create your own custom subtheme with your own styles. Then on the block layout page, you can place a variety of blocks into the regions for the AMP theme you’ve chosen.

That’s the big overview. Let’s dig into the details.

Installing the AMP module, theme and library

If you’ve used Drupal 8, you’re probably already familiar with Composer, a packaging tool for PHP that helps to install dependencies for a project. We’ll use Composer to install a PHP library that converts raw HTML into AMP HTML; Composer will also help to get that library working with Drupal. That’s true both for the Drupal 8 and the Drupal 7 versions of the AMP module.



The workflow we recommend involves using a Drupal module named Composer Manager. A composer.json file within the AMP module declares the dependency on the AMP PHP library. That library in turn has its own dependencies. Other modules that also have their own composer.json files could declare the same library dependencies. So Composer Manager takes care of going through all the modules installed on a site, collecting the info in their composer.json files, and bringing all of that information together so that multiple modules don’t end up installing the same dependencies that might conflict with each other.

However, the AMP module does not explicitly require Composer Manager as a dependency. Alternate workflows can make use of module Composer files without using Composer Manager. For example, Karen Stevenson provides an overview of how to use Composer to manage your entire site installation in her article, Goodbye Drush Make, Hello Composer!

If you are working with Drupal 7, you might find Composer Manager particularly useful. Drupal 8 has a built-in PHP autoloader. This allows you to take advantage of other PHP classes in a project without a require statement that specifies the exact file where that code is located. Composer Manager provides an autoloader for Drupal 7, so that the AMP module can make use of the code found within the AMP PHP library that Composer Manager installs.

Drush makes working with Composer Manager even easier. With Drush installed, several CLI commands, which we will cover below, can help to make use of Composer Manager. In addition, when you enable modules through Drush, Composer Manager can automatically install dependencies.

Whether you are working with a Drupal 7 or a Drupal 8 site in your local development environment, make sure you are using the most recent version of Drush 8, which now works with both Drupal 7 and Drupal 8 sites.

Let’s get ready to set up your Drupal site with AMP. With your local prepped, you can type the following terminal command within the directory where your Drupal site is located:

drush dl amp, amptheme, composer_manager

This will download the AMP module, the AMP theme and the Composer Manager module (if you don’t already have Composer Manager installed).

Next we’re going to enable the first items we’ll need to get started.

drush en composer_manager, amptheme, ampsubtheme_example

Notice we’re not enabling the AMP module yet! We want Composer Manager enabled and working before we do so. We’re also enabling an example subtheme included with AMP Theme: ‘ExAMPle subtheme.’ If you review the code in the subtheme, you can see how to set up custom styles for AMP pages. You can create your own subtheme if you like and install that instead. The default configuration for the AMP module sets the AMP Theme to ‘ExAMPle subtheme.’ So if you just want to try out the AMP module, enabling the example subtheme is a handy way to see how the module and theme work together to provide valid AMP HTML with a custom design.

You should now be able to enable the AMP module using Drush, and when you do so, Composer Manager will take care of downloading the AMP library and its required dependencies. Enabling the module in the UI does not trigger Composer Manager to install dependencies, so Drush is the preferred way to enable the AMP module.

drush en amp

You should get a message about dependencies being downloaded. If that doesn’t happen, then the modules should provide an error message about the AMP library not being available. Here are some things you can try for troubleshooting.

If you are using Drupal 8:

• Go to the docroot for your site and enter composer drupal-update. If that fails, you may need to apply a patch from https://www.drupal.org/node/2405811 with the following command: curl https://www.drupal.org/files/issues/2664274-19-fix-composer.patch | patch -p1.

• You may also need to go to the module directory for composer manager and enter php scripts/init.php, then return to the docroot and try composer drupal-update again.

If you are using Drupal 7:

• Go to the docroot for your site and enter drush composer-json-rebuild followed by drush composer-manager install. Check /admin/config/system/composer-manager to verify everything is green. If so, try drush en amp again.

• You may find it useful to go to sites/default/files/composer and enter composer install if the above doesn’t work. Then try drush en amp again.

• If you do not find a composer directory in sites/default/files, check the Composer settings at /admin/config/system/composer-manager/settings. This should show you where you can find the composer directory that contains the composer.json file, which allows you to run composer install in that directory.

Once the AMP library is installed, if you later need to update to a newer version, drush composer-manager update should take care of the update. Review the Composer Manager documentation for additional details.

You should now have the AMP module, AMP theme, AMP example subtheme and AMP library all installed and enabled. Next, we need to configure your site to make use of these new tools.

Configuring your site for AMP

Once everything is installed and enabled, you can find the AMP configuration page at /admin/config/content/amp. The first thing you’ll see is the list of your site’s content types. Take a minute to think about which content types should have AMP versions. It might not be all of your content types! News articles, blog posts and basic content-oriented pages are all great candidates for AMP.

View mode information on AMP configuration page in Drupal 8

To enable a particular content type for AMP, click on the “Enable AMP in Custom Display Settings” link. On the next page, open the “Custom Display Settings” fieldset. Check the AMP box, then press Save. This will bring you back to the main AMP config page. You’ll then want to press the corresponding “Configuring AMP view mode” link for that content type. On that page, you’ll be able to select which fields should display and the field formatters that each will use.

Custom display settings, found on the default display mode under the Manage Display tab for a content type in Drupal 8

The first thing you’ll want to do is change the body field to use the AMP Text field formatter. There are also custom AMP field formatters for images, videos (file fields) and iframes (text fields). More field formatters may be added in the future. This should help get you started. Some of the field formatters, like AMP Image, have additional options you might want to review by pressing the gear icon, which appears to the right of where you select that field’s formatter.

In Drupal 8, on the Manage Display tab for a content type, under the AMP view mode you can select AMP field formatters for each field

This combination of AMP view modes and field formatters is the heart of how your content is transformed into an AMP page. The AMP Text field formatters are particularly important in converting freeform text blocks that might contain embedded content. Some items like Twitter embeds will be automatically converted to the equivalent AMP components. Items with markup that is invalid for AMP, and which cannot be converted by the library into AMP markup, will be filtered out of the markup so that the page will validate as AMP.

Selecting an AMP theme

While the AMP module’s view modes and field formatters take care of the main content of the page, the AMP theme changes the markup outside the main content area of the page. The AMP theme also allows you to provide custom styles for your AMP pages. You will likely want to do that so that your AMP pages have branding similar to the non-AMP pages on your site.

On the main AMP config page, you’ll also want to make sure that the setting for the AMP theme is set to the ExAMPle Subtheme or your custom AMP subtheme. The AMP Base theme changes markup necessary for all AMP-based themes. In Drupal 8, AMP Base uses core’s Stable theme as its parent theme in order to keep the markup as lean and class-free as possible.

On the AMP configuration page, you can select the AMP theme

If you want to create a custom AMP subtheme with your own styles, take a look at how the ExAMPle subtheme does so. AMP does not allow custom JS, so the main thing you’ll be interested in is providing some custom styles and any markup changes necessary to support those styles. In Drupal 7, custom styles go in amp-custom-styles.css within the css directory at the root of the custom theme. In Drupal 8, the file where you’ll put your CSS is amp-custom-styles.html.twig, in the amp-css directory, which is inside the templates directory at the root of the custom theme. That’s because the CSS is embedded in the head of the html.html.twig file. In order for Drupal 8's Twig template engine to import code into a Twig template like html.html.twig, that code must be in a Twig template (and not another type of file) located in the templates directory of the theme.

Please note that the custom CSS has a maximum size of 50K! So this shouldn’t be all the styles for your entire site, but just whatever minimal styles are needed for AMP pages. If you want to use Sass to generate that CSS, you could definitely do so, as long as it compiles down to the one CSS file needed by the theme. Make sure to review the AMP Project guidelines for styling pages.

After you have the AMP theme selected, go to that theme’s block layout page. You will likely want to review block placement. You probably only need a few blocks: AMP pages are geared towards loading quickly and providing a great reading experience, so extensive menus for navigating the site may appear out of place (and could be difficult to implement without custom JS).

Select a limited number of blocks for your AMP theme on the block layout

Let’s check one last thing on the main AMP config page. There’s a checkbox near the bottom that enables full processing of the entire page’s markup through the AMP library. I highly recommend checking this box, as that helps to further ensure your page will be valid AMP HTML. If a module adds an attribute to some template somewhere, or if a block has an image that should be converted, this final pass through the AMP library will help to catch that.

Make sure to check the option to run the full page through the AMP library

Analytics and ads

If you’re using Google Analytics, the AMP config page lets you enter your analytics ID so that basic Google Analytics tracking can be added to your AMP pages. The AMP specification also provides an AMP Pixel component that can be used for analytics in a way similar to how image tracking pixels work. At present, you can set up one AMP Pixel tracker by entering the domain name and URL path for the tracker. The random number tracking component is there as an example to see how this sort of tracking works. More robust AMP pixel tracking and additional analytics options may be available in the future.

The AMP configuration page offers options to configure ads and analytics for your AMP pages

You can also enter account information for Adsense and Double Click ad accounts on the AMP config page. Once you do so, if you return to the block layout page for your AMP theme, you can place ad blocks for those networks. In Drupal 7, you are currently limited to four ad blocks for each; Drupal 8 does not have a limit on the number of ad blocks. When you place each ad block, you’ll also need to enter the slot ID from your ad network of choice for that particular ad.

View AMP pages

Congratulations! Your site can now display AMP pages! If you are editing an item where its content type has an AMP view mode enabled, you will then have an option to save and view the AMP page. You can also add ‘?amp’ to the end of the URL for the page. If the URL for the page already has a query string, you can add ‘&amp’ to the end of the existing URL. Voilà! You can now see how your AMP page looks and decide if you want to make further changes.

If some of your content appears to be missing, the AMP library validator may have removed it from the final markup. All of your original content remains within your site: it just might not show up on an AMP page. To see what actions the validator has taken, add ‘&warnfix’ to the end of the page’s URL; warning messages will then display regarding any fixes the AMP library made in order for the page to validate as AMP HTML. There is also an option on the main AMP config page to show warning messages on all AMP pages.

You can also debug your AMP pages with in-browser developer tools like Chrome Dev Tools that have a console tab. The AMP JS validator shows error messages in the console tab that can help you determine if you need to address  a problem in order for your page to validate as AMP.

Our goal is for you to have flexibility and control with how your AMP pages display. That does mean a little work to get AMP set up on a Drupal site, but we think that’s time well spent. We want your AMP pages to look just the way you want. AMP pages can be beautiful as well as fast!

Why you should try out AMP

Now that you have AMP all set up, let’s talk about why it’s worth the effort.

The web could definitely use a jump start. Too many sites get bogged down with ads, trackers and other JS. AMP offers one way to help alleviate that pain. By clamping restrictions on sites and focusing strictly on the mobile web, AMP offers impressive results. Valid AMP pages with proper schema data get cached in Google’s CDN, and furthermore can be preloaded before you even get to the page. The end result feels like magic: click a link to an AMP page, and it appears before you in a flash. Some tests have shown AMP pages rendering four times faster than equivalent non-AMP pages, while using ten times less data. Those are pretty exciting results!

Google has rolled out carousels of AMP articles in their search results, and Twitter supports AMP now as well. I’d expect we’ll see more and more places that support AMP. That’s one of the big benefits of AMP being an open source project: anybody can create an implementation to show the AMP versions of pages.

As more sites and services make use of AMP pages, creating AMP versions of your content will be more and more key. Yet despite the opportunities AMP offers, I have heard some concerns about AMP, and I wanted to discuss them.

Isn’t this like m.example.com sites with separate content for mobile? Thankfully, with the solution we’ve worked on for Drupal, you don’t need to create two entirely different sites nor do you need to keep two sets of content in sync. You can simply provide a way for the content in your current site to be transformed into AMP HTML. That gives you the benefits of AMP’s speed without too much hassle. This also doesn’t rely on browser sniffing, like m. sites did. You don’t need need to detect if the URL request comes from a mobile device, which could be a huge pain. The site linking to yours determines whether they should provide a link to the AMP or non-AMP page.

Is AMP too prescriptive in how it tackles site speed? Tim Kadlec asks that question and more in his proposal to create Content Performance Policies as an alternative to AMP. CPP could be a standardized way to say which performance standards your site adheres to, and in theory a browser could enforce adherence to these standards. Tim speculates that AMP could end up being an implementation framework to adhere to a particular CPP standard.

Can’t sites just use good practices and be fast without AMP? I think it’s great to see all the energy and competition around ways to make sites faster. Front-end performance is something I’m passionate about because it’s one more way to make the web available to all, not just those with fast devices and unlimited data. Learning how browsers work can help you to better structure your HTML, CSS and JS, fonts and images in ways that make sites speedy. There’s nothing stopping anybody from using that knowledge to make a very fast site without using AMP, a fact Paul Bakaus from the AMP project acknowledged in “Life After AMP” and in this video about AMP.

That said, knowing performance best practices and putting them in place on media-rich publishing sites is another matter. Digital publishers are under a lot of pressure, and business needs often result in ads and analytics that serve business goals, but can result in slower page loads and sluggish scrolling. Even with solid work on front-end performance optimizations, sometimes there’s only so much you can do to speed up a site.

While in the future Content Performance Policies might encourage publishers to make fast sites on their own, right now publishers can get a super fast mobile site with AMP and see firsthand the results of improving user experience with that speed. AMP forces a site to adhere to some tight limits, putting the most problematic items for performance either off limits or in a controlled sandbox. I’ve been super impressed when I’ve seen real AMP pages in action through Google AMP article carousels. I think if publishers give this a try, they’ll be impressed too. There are AMP components for analytics, so publishers can get some real world data on how well this works.

My bet is that when somebody encounters an AMP page in the wild, they’ll be wowed by the speed, and they’ll be more likely to read the article and share it. If publishers see that engagement in their analytics, that will be real world tangible evidence of the importance of front-end performance on their own sites.

With that sort of data, publishers might decide to be more selective about the JS, trackers and other items that can slow down their main site. Maybe if Content Performance Policies become more than just a proposal, publishers will rework their entire sites to adhere to those emerging standards. Perhaps they set performance budgets for their sites as a whole. Those would all be good things.

No matter the size of your site, consider giving AMP a try. With the Drupal module and theme, as well as the AMP PHP library, there’s a good way to try out AMP with your site. With a little configuration and some CSS, you can have a fast mobile site that matches your branding. You can then test the metrics for visits to AMP pages versus non-AMP pages. You might just find that front-end performance could be a key feature to further pursue. So give it a shot!

Want to learn more about AMP and Drupal? Matthew Tift, Karen Stevenson and I will be presenting a session at DrupalCon New Orleans, “AMPing up Drupal.” We hope to see you there!

And with that, I’ll speed you on your way.

Photo by Anton Pinchuk, used under Creative Commons license.