Posted on Leave a comment

How to Embed Code Snippets in a WordPress Post, and Make It AMP and SEO Friendly

The Problem

WordPress’s Gutenberg editor has a native Code block. It looks like this:

function storefront_post_nav()
{
    $args = [
        'next_text'    => '<span class="screen-reader-text">' . esc_html__('Next post:', 'storefront') . ' </span>%title',
        'prev_text'    => '<span class="screen-reader-text">' . esc_html__('Previous post:', 'storefront') . ' </span>%title',
        'in_same_term' => true,
    ];

    the_post_navigation($args);
}

I’m usually a big fan of native solutions, but this one is just not good enough. It doesn’t have, for example, semantic highlighting, which makes it harder to read. You can do better.

The Solution

GitHub Gists

GitHub Gists are a way to instantly share code, notes, and snippets. It is a popular way to embed code snippets in web pages.

You are probably familiar with Gist snippets. It looks like this:


Basic GitHub Gists embedding

To create a Gist, open a free Github account and navigate to https://gist.github.com/[your_user_name]. Then, click the (+) sign on the top right.

To get semantic highlighting, for making your code snippet more readable, make sure to do 2 things:

  1. Add the relevant filename extension
  2. Add the language opening tag (if required by the language)
Make sure you get semantic highlighting

When you are done, copy the embed code from the top right of the Gist into a Gutenberg Custom HTML Block.

Copy your embed code into a Custom HTML Block

So far, so good. but this method doesn’t support AMP out-of-the-box. And, as it JavaScript dependent, it might not be SEO friendly.

We will fix that…

Making your Gist snippet show on AMP pages

AMP is an open-source HTML framework developed by the AMP Open Source Project. AMP is optimized for mobile web browsing and intended to help webpages load faster. AMP has a great official WordPress plugin, which I’m using. Gist snippets don’t work on AMP pages out-of-the-box — they just won’t show.

To fix that and display Gists on AMP pages, we first need to enable the official amp-gist component, by calling a script in the head of the relevant pages:


Then, we can add this code in an additional Custom HTML block:

<amp-gist data-gistid="400f4d0338a306c5e6db8c1819e78d5d" layout="fixed-height" height="303">

The data-gistid is your Gist ID. You can get from the src attribute of your Gist embed code. It is the part after your user name. Don’t forget to remove the .js file extension when copying. The layout attribute is constant. The tricky part is the height attribute. You need to go to your Gist page on GitHub and use the DevTools to get the Gist actual height.

Getting your Gist height using DevTools

It might look hacky and fragile, but, as for now, this is actually the oficial soulutuon — and it works.

Now, your Gist will show on AMP pages. Next, we’ll make it SEO friendly.

Making your Gist snippet SEO friendly

We use JavaScript to embed our Gist. Generally, it is unclear if and how Google indexes content generated by JavaScript. So, to be on the safe side, we’ll make a no-script fallback.

You might be familiar with a native noscript HTML tag which was designed for similar cases — it will display a fallback when JavaScript is not supported. If you are like me, your first guess would be adding a simple noscript tag on a new Custom HTML block. I did. It didn’t work. The noscript tag was converted to <!–noscript–> which disables its functionality and always displays the code in it, regardless of JavaScript support. I contact the AMP plugin developers and got this response:

Custom JS is not allowed in AMP (unless using amp-script), and will be removed. Thus by default activating AMP with a theme will cause it to behave as if JS is turned off in the browser. To improve the graceful degradation process, in addition to removing custom scripts it will also unwrap noscript elements so that their content becomes the AMP version by default.

Luckily, they also supplied a simple and elegant solution — nesting the noscript tag inside the amp-gist tag, like this:


This way, the code tag will be displayed when (and only when) JavaScript is not available, increasing the chances it will be indexed by Google.

Leave a Reply