How to Add Related Posts to Accelerated Mobile Pages in WordPress

This project shows how to add Related Posts to Accelerated Mobile Pages in WordPress using the Contextly content recommendation REST API. The solution doesn’t use a plugin, is written in PHP and produces 100% valid AMP HTML.

Bare Bones AMP Pages – No Related Posts

I’m a Contextly subscriber and use the Contextly plugin to display related posts for increased reader engagement. I also installed the Enable Accelerated Mobile Pages AMP plugin by Automattic which dynamically generates AMP versions of post pages by removing non-compatible content. Because the Contextly plugin is not AMP compatible  related posts are not displayed. Related posts are very important because my site visitors use them a lot. I therefore needed an AMP compatible solution.

Contextly REST API

I asked Contextly if an API is available and was pleased to learn about their REST API. The API specification is provided on a request basis so I won’t publish the one-page spec here but will explain how to use the it.

The REST API request format is:{conanical_url}&load_snippet=true

where the {canonical_url} parameter is the post Permalink in % encoded format. Paste the following URL in the web browser to view the API JSON response:

An AMP article with Related and Interesting Posts at the bottom can be viewed here:

Compare responsive mobile page (as generated by the Contextly plugin) to the AMP page related posts using the Contextly REST API:

WordPress Related Posts - Responsive Page vs Accelerated Mobile Page

WordPress Related Posts – Responsive Page vs Accelerated Mobile Page

The same set of related posts are displayed! The minor differences in AMP formatting are due to my preferences.

Why not use amp-list for Related Posts?

The amp-list element is commonly used for displaying related posts and featured articles in AMP HTML pages. I suspect Contextly will support AMP in the future which would simplify the related posts code to something like:

<amp-list src="" width=600 height=450 layout=responsive> 
  <template type="amp-mustache">
    <!-- mustache template goes here -->

Aside: The source URL is fictional.

How to Implement Related Posts for Google Accelerated Mobile Pages (AMP)

The high level AMP Related Posts design is:

  • Create a PHP class to retrieve and encode the Contextly API related content recommendations as a JSON object.
  • Put the related and interesting posts data in a PHP array.
  • Render the related and interesting posts using the array in a Mustache template.

Because all processing is done in PHP on the web server only HTML is rendered for 100% AMP validation/compatibility. My Google Search Console AMP page report says: “Congratulations, you have no AMP page errors”:

Google Search Console - Accelerated Mobile Pages Report

Google Search Console – Accelerated Mobile Pages Report

BTW – I’m not sure what caused the red error spike in May. I hadn’t made any changes and the report corrected itself.

AMP Related Posts for WordPress – Code Dependencies and Structure

My WordPress solution uses the following plugins, libraries and APIs:

  • AMP plugin by Automattic
  • AMP Custom Template
  • Mustache library for PHP
    • Mustache is an elegant way to produce HTML using easy to read code templates. It’s free and simple to install.
  • Contextly Plugin
    • While the plugin is not used in this AMP solution, it is needed to get an API key and have Contextly index your website. You’ll also want the same related posts on the both the normal and AMP versions of the site for a consistent user experience.
  • Contextly REST API

The project folders and files are in the WordPress /wp-content folder per the following directory tree diagram:

WordPress Related Posts for Accelerated Mobile Pages - Project Directory Tree

WordPress Related Posts for Accelerated Mobile Pages – Project Directory Tree


  • /wp-content/lib/mustache is the Mustache library for PHP.
  • /templates/related-posts.mustache is the Mustache template.
  • /amp/hht-single.php and hht-style.php are my AMP Custom Template HTML and Style (CSS) files.
    The “hht” prefix is short for HandymanHowTo.
  • /include/amp-contextly-related-posts.php is the core code logic to invoke the Contextly REST API, extract and render the related posts in the Mustache template. It’s included by functions.php.
  • /my_child_theme/functions.php hooks in the related posts feature via add_action().

AMP Related Posts Implementation – PHP Source Code

Now I’ll explain the related posts logic flow and PHP source code.

AMP Custom Template

I created an AMP Custom Template to add missing functionality and tailor the look & feel of AMP post pages. See the excellent Tech Prezz tutorial for details.

For example, my hht-single.php post template and hht-style.php style template are set via this code snippet in functions.php:

// Use a custom post template
function set_hht_amp_custom_template( $file, $type, $post ) {
  if ( 'single' === $type ) {
    $file = dirname( __FILE__ ) . '/amp/hht-single.php';
  return $file;
add_filter( 'amp_post_template_file', 'set_hht_amp_custom_template', 10, 3 );

// Use a custom style template
function amp_set_custom_style_path( $file, $type, $post ) {
  if ( 'style' === $type ) {
    $file = dirname( __FILE__ ) . '/amp/hht-style.php';
  return $file;
add_filter( 'amp_post_template_file', 'amp_set_custom_style_path', 10, 3 );

The related and interesting posts are displayed by the do_action() call in the hht-single.php AMP Custom Template after the call to $this->get( 'post_amp_content' ):

<div class="amp-wp-content">
  <h1 class="amp-wp-title"><?php echo wp_kses_data( $this->get( 'post_title' ) ); ?></h1>
  <ul class="amp-wp-meta">
    <?php $this->load_parts( apply_filters( 'amp_post_template_meta_parts', array( 'meta-author', 'meta-time', 'meta-taxonomy' ) ) ); ?>
  <?php echo $this->get( 'post_amp_content' ); ?>
  <?php do_action( 'amp_get_contextly_related_posts' ); ?>

Child Theme – functions.php

The following code is added to the child theme functions.php. It includes the related posts main module amp-contextly-related-posts.php then hooks in the ampDisplayContextlyRelatedPosts() function so it can be invoked from hht-single.php via do_action(). A new object is created to render the related and interesting posts.

// Contextly Related Posts for Google AMP
include_once( get_stylesheet_directory() . '/include/amp-contextly-related-posts.php' );

/* Called by <?php do_action( 'amp_get_contextly_related_posts' ); ?> in the AMP page template. */
function ampDisplayContextlyRelatedPosts()
  if ( !is_amp_endpoint() )
  $amp_related_posts = new AmpContextlyRelatedPosts();
  if ( $amp_related_posts->getInitStatus() == false )
    return; // class initialization failed. Nothing will be displayed on the AMP page

  // The Related and Interesting posts will be displayed if successful,
  // otherwise nothing is shown on the web page.
add_action( 'amp_get_contextly_related_posts' , 'ampDisplayContextlyRelatedPosts' );

This project is continued in How to Add Related Posts to Accelerated Mobile Pages in WordPress – Part 2.


Bob Jackson

Copyright © 2016   Reproduction strictly prohibited.

, , , ,

No comments yet.

Leave a Reply