How to Use Ghost’s Built-In AMP Support

In this tutorial I’ll walk you through all the key aspects of using Ghost’s in-built AMP support.

How to Use Ghost’s Built-In AMP Support

Note: this article assumes you are already familiar with how to create AMP valid pages, and as such will be focused on the details specific to using Ghost and AMP together. If you’re new to AMP, check out:

I’m also assuming you have knowledge of how to create a typical Ghost theme. If not, you can learn how by reading:

Ghost’s Built-In AMP Support

In actual fact, Ghost has automatic AMP support without you having to lift a finger. The AMP version of any post can be visited just by appending /amp/ to its URL. The regular version of any post will also automatically include a link in the <head> section to let Google know this AMP version is available.

Owing to this automated functionality, if you visit a Ghost post using Chrome with the AMP Validator extension installed, you’ll see a little blue link icon indicating an AMP version of the page has been detected.

How to Use Ghost’s Built-In AMP Support

Click the icon and you’ll be taken to the post’s AMP version, at which time you’ll see the icon turn green to indicate valid AMP code.

How to Use Ghost’s Built-In AMP Support

This automated AMP support is only for single posts, however. Other types of content like your home page or tag pages won’t have AMP versions unless you manually develop your whole theme to be entirely built out of AMP compatible code.

Using a Custom AMP Template

By default, the presentation of AMP posts on Ghost is controlled by an internal template. To see how this template is put together, and get a reference for how AMP works with Ghost, you can find this default template inside your Ghost installation at /core/server/apps/amp/lib/views/amp.hbs

If you prefer to use your own markup and styling for your AMP posts you’ll need to create a template named “amp.hbs” in the root folder of your theme.

Your AMP template won’t be able to extend on the regular “default.hbs” template, as you usually would when creating Ghost theme templates. Rather, it should be created as a complete standalone HTML document with its own html, head and body elements.

The reason for this is that you need to ensure:

  1. You are using the essental AMP code in the opening <html ⚡> tag and in the head section
  2. CSS is loaded in an AMP valid way
  3. Required AMP scripts can be loaded by Ghost
  4. No custom JS is being loaded

A “default.hbs” file in a typical Ghost theme would not meet the above requirements, hence the need to have a self-contained “amp.hbs”.

Handling CSS

There are a couple of things to be aware of with CSS in your AMP templates.

Firstly, if you are loading in a custom font from one of the approved sources, be sure you do so in an AMP valid way. For example, a Google font might be loaded via a URL like //fonts.googleapis.com in your “default.hbs” template, but to pass validation in your “amp.hbs” template you would need to change that to https://fonts.googleapis.com

The other primary consideration is that you’ll need to have all your custom CSS inline between <style amp-custom>...</style> tags in the <head> section, with your CSS not exceeding 50kb and not breaking any AMP CSS rules.

There are two ways to go about this:

  • Write AMP specific CSS and use it solely on AMP pages.
  • Write CSS for your entire site that follows AMP’s rules and use it everywhere.

If your “regular” site really needs some heavyweight CSS you might need the former option, but otherwise you may find it easier to use the latter.

Keeping your site’s whole stylesheet below 50kb might seem daunting given some popular CSS frameworks are more in the region of 120kb – 150kb, but if you set out with the 50kb goal in mind it’s quite achievable. For example, the unminified CSS of the Ghost default theme Casper is 45.5kb.

If you wish to use this approach you can create a partial template named “css.hbs” and place all your site’s CSS code directly inside. Then in your “default.hbs” template you can load this CSS with:

<style>
  {{> css}}
</style>

And in your “amp.hbs” template instead use:

<style amp-custom>
  {{> css}}
</style>

To squeeze the most out of your CSS you can also minify it before you place it into this partial. You’ll be able to monitor the file size of this partial to get a pretty good idea whether you’re within the 50kb limit.

Ghost Head and Foot Expressions

In the head section of your “amp.hbs” template you’ll need to include the expression {{amp_ghost_head}} instead of the usual {{ghost_head}}. This will ensure no JS is output in the head, which would break AMP validation.

And, unlike in regular Ghost templates, you should omit the {{ghost_foot}} expression all together.

Accessing Data

All the content of a post can be exposed in the “amp.hbs” template by using the block expression {{post}}...{{/post}}. In between these tags you can use the following helpers to output content:

You can also access all @blog global data from within the “amp.hbs” template, such as @blog.title and @blog.url, whether in or outside the {{post}}...{{/post}} expression.

Using AMP Elements

As you know, AMP requires a number of its own custom elements to be used in place of regular HTML elements. This means there are two aspects of your Ghost sites where you need to ensure the correct AMP elements are used:

  1. The post content drawn from the back end
  2. Your code in your “amp.hbs” template

In your post content Ghost can automatically detect images, iframes, gifs and audio elements then rewrite them into their AMP counterparts.

To enable this you’ll need to include {{amp_components}} in your head section, just before the closing </head> tag, which will output any additional scripts AMP’s custom elements required. You’ll also need to use {{amp_content}} instead of {{content}} so the correct markup for custom elements is produced.

As for the code in your “amp.hbs” template however, you’ll need to add any required AMP elements manually. For example, if you want to include the post’s featured image you would use:

<amp-img src={{image absolute="true"}} width="600" height="400" layout="responsive"></amp-img>

Wrapping Up

That covers all the essentials of tapping into Ghost’s in built AMP support. Let’s have a quick recap of the key points:

  • AMP functionality works automatically on single posts.
  • To see the AMP version of a post append /amp/ to its URL.
  • To customize the presentation of AMP posts create a template named “amp.hbs” in your theme’s root folder.
  • Ensure CSS is used in an AMP valid way.
  • Consider coding AMP valid styling for your entire site and placing it into a partial template so it can be used in both your “default.hbs” and “amp.hbs” templates.
  • Include {{amp_ghost_head}} instead of {{ghost_head}}
  • Don’t include {{ghost_foot}}
  • Include {{amp_components}} right before the closing </head> tag.
  • In the “amp.hbs” template you can use the {{post}}..{{/post}} block expression and all @blog global data.
  • Use {{amp_content}} to output content. This should be placed inside the {{post}}...{{/post}} block.
  • Ensure any elements hard coded into the “amp.hbs” template use AMP custom elements where required.

That brings us to the end of this quick tutorial. Keep an eye out for more tips on using AMP with other site creation platforms, coming very soon!

Further Reading