Setting up Jekyll for AMP

Setting up Jekyll for AMP

In the following article I will be taking you through how I enabled AMP pages for my Jekyll blog.

  • Jekyll project structure
  • Configuring the layouts
  • Adding a Service Worker to an AMP Page
  • Adding Google Analytics
  • Setting up canonical and amphtml meta tags
  • How to build both sites in one command and include it in your CI build

As always you can find an example of all of this to reference on my repo at Github

For an introduction and guide to AMP, you can go to the official site here which is an excellent source for getting started.

Jekyll project structure

If you take a look here at my Github repository you can see the following new folder _layouts-amp and a new file called _config-amp.yml.

In the _layouts-amp folder we have a copy of the _layouts folder. This will be used for the necessary html layout changes needed.

The new _config-amp.yml is a copy of our _config.yml and we will be adding some additional settings to it so we can specify new defaults for it to use.

This means we will have to run to separate processes to produce 2 versions of the site but don’t worry I will cover how we can make this simpler later.

In your _config-amp.yml add to the bottom the following settings.

destination:   _site/amp
layouts_dir:   ./_layouts-amp

      path: "_posts"
      layout: "default"

and change your baseurl to

baseurl: "/amp"

Now go to your command line and run the following command

With the additional settings it will produce a copy of your existing site
into a sub folder called /amp. Now for the fun part, customising the

## Configuring the layouts

AMP requires us to strip the majority of things we have come to take
as standard, and markup our content in a certain way so that it can
be easily processed. This means we need to make the following changes

In our default.html change it to

{% raw %} <!doctype html>

{% include amp-head.html %}

{{ content }}
{% include amp-footer.html %}

{% endraw %}

Notice we have in our html declaration ```amp```. This is an example
of things we need to change. Also pay attention to the site-title link.
Because I host on S3 and haven't got around to figuring out how to set
sub folders to look for index.html by default I have had to add
index.html to the end.

page.html and post.html I have left the same but you may need to amend
yours depending on the markup you have. Mine is very basic (on purpose)
so it validates by default.

In the above snippet I have referenced two files, amp-footer.html and
amp-head.html. We need to create these two files in our
folder. There content will look like so


{% raw %} {% if page.title %}{{ page.title | escape }}{% else %}{{ site.title | escape }}{% endif %} {% if %} {% endif %}

{% endraw %}

With AMP you should include all your CSS inline. It also needs to be as small as possible and be wrapped in a new special
tag called ```<style amp-custom>```. I have deliberately only included the absolute basic CSS to keep it functional.

This tag is a direct relation to this JS include file ``````. This contains the definitions
for the new tags that you are able to wrap common functionality into.

This also allows us to use the ```<style amp-boilerplate>``` which from what I can tell is a required set of styles
to allow AMP sites to work.


{% raw %}

<h2 class="footer-heading">{{ site.title }}</h2>

<div class="footer-col-wrapper">
  <div class="footer-col footer-col-1">
    <ul class="contact-list">
      <li>{{ site.title }}</li>
      <li><a href="mailto:{{ }}">{{ }}</a></li>

  <div class="footer-col footer-col-2">
    <ul class="social-media-list">
      {% if site.github_username %}
        {% include icon-github.html username=site.github_username %}
      {% endif %}

  <div class="footer-col footer-col-3">
    <p>{{ site.description }}</p>

{% endraw %}

The only changes on here are the addition of the amp-analytics and
amp-install-serviceworker tags. I will explain these below.

So now if we run the build command again we should have a new amp compatible
site in our /amp sub folder.

## Adding Service Worker functionality

Because we are restricted by including external javascript and CSS in AMP, we have to use their built in libraries
to get access to functionality such as Service Workers. Above you can see we have included the script

``` and then to enable our service worker we use this tag. `````` ## Adding Google Analytics Just like the service worker, for analytics there is an AMP library we can call upon to pass parameters through. The script to link to is `````` and then for Google Analytics we can do this in our footer ```

Notice that in the type attribute I have specified googleanalytics. This can be changed to your preferred anaylytics
provider. See the links at the end of tHe document for more advanced usages. Just replace my account ID with your own.

## Setting up canonical and amphtml meta tags

{% raw %}{% endraw %}```

This line specifies the link back to our full html page. It is required to allow the user/browser easy access back to the full page.

A bit of functionality we haven’t configured yet is the addition of the variable canonical_baseurl. Open up your _config.yml and add the following line in

And in your _config-amp.yml add the following line

canonical_baseurl: “”```

Now in your head.html add the following code

{% raw  %}
{% if page.url == '/amp/' %}}
<link rel="amphtml" href="{{ page.url | prepend: site.canonical_baseurl | prepend: site.url | append: 'index.html' }}" />
{% else %}
<link rel="amphtml" href="{{ page.url | prepend: site.canonical_baseurl | prepend: site.url }}" />
{% endif %}
{% endraw  %}

This lets the search engines know there is an equivalent AMP file to our full html page.

All this can be seen in my Github repository.

How to build both sites and include it in your CI build

In your package.json add the following line under scripts

Now in your build script change your ```jekyll build``` to ```npm run build```

Every time you want to build both sites just run the following from bash

npm run build```

Done! Now you can prepend /amp/ to any post and you will get your AMP version.

External resources