How to Add FAQ Schema to Jekyll Pages With Liquid

October 30, 2020 | Jameson Zimmer

FAQ schema is one of my favorite underutilized SERP features for SEO.

I wasn’t able to find an off-the-shelf solution for adding FAQ schema markup to Jekyll sites, but it’s quite simple to do so by updating your site templates.

My solution involves updating your site template(s) so that FAQ items can be entered as front matter in your posts, and output into JSON and HTML automatically.

Here are the details for all y’all copy-paste cowboys out there! 🤠

1. Add <script> tag to default.html layout template

Pop open your _layouts folder and add this to the <head>. You can really add it anywhere but I like to put it directly before the closing </head> tag:

{% if page.faq %}<script type="application/ld+json">{"@context":"","@type":"FAQPage","mainEntity":[{% for item in page.faq %}{"@type":"Question","name":"{{item.question}}","acceptedAnswer":{"@type":"Answer","text":"{{item.answer}}"}}{% if forloop.last == false %},{% else %}]}</script>{% endif %}{% endfor %}{% endif %}

2. Add HTML output to the layout templates as needed

Chances are, you have several layout templates for your website such as “post,” “page,” etc.

You’ll need to add the HTML output anywhere you want the FAQ schema to output on the page as HTML for your readers.

For all layouts that will have FAQ schema, go ahead and scroll down to the {{ content }} liquid block in your layout file and add this:

{% if page.faq %}
{% include faq-schema-content.html %}
{% endif %}

Assuming the default Jekyll site structure with a default, post, and page layout, you’ll need to add this to your “post.html” and “page.html” layouts only. You don’t need to add it to the default.html file.

3. Add the FAQ include to your _includes file

Next, go into your _includes directory and create a file called faq-schema-content.html, with the following contents:

<h2>Frequently Asked Questions</h2>
{% for item in page.faq %}
{% endfor %}

You may want to update this to pretty up your FAQ with accordion for each entry, some kind of CSS box around it… it’s up to you :)

4. Add FAQs to your content front matter

Now that all that’s sorted, you should be able to add a “faq” item to your front matter and have the content output to HTML and JSON for your pages.

Here’s an example post with FAQ schema added to front matter:

layout: post
title: "My Amazing Post"
- question: "How do I add FAQ schema to my Jekyll site?"
  answer: "simply read Jameson's <a href=''>helpful blog post</a> on the topic."
- question: "Why bother adding FAQ schema to my site?"
  answer: "Because it will double the size of your entry in the SERP for some queries, and help direct traffic to your most relevant pages."

It’s important to use double quotes for the input, so that you can include single quotes around link targets in the FAQ items without breaking parsing of the front matter.

See example above for what a link should look like.


The main drawback of this solution is that you can’t access custom data in your site’s _data directory for FAQ items. If you need to do this, you’ll have to add the JSON and markdown/HTML to your post directly, so that you can call data using Liquid in the text.

You might also be able to solve for this case by using includes in a clever way, but at a certain point if probably makes more sense to just upgrade from an SSG or go to something like Gatsby that has better data support and customization…

Basics of using FAQ schema

Why bother with FAQ schema for Jekyll sites?

Because it takes some effort to set up, few people outside highly competitive affiliate verticals will bother.

But once set up, it doubles your result size in Google search and makes it easier for the search audience to find links to relevant pages on your site or locate a specific .

I’ve also seen some great results from including highly reference-friendly material e.g. statistics and facts in schema, resulting in an increase of linked references.

That said, it’s not always worth bothering with. As you may notice, I haven’t bothered adding it to my personal site you’re reading right now — I only bother for higher-traffic projects.

FAQ schema SERP appearance

Once in place, it’s up to Google to decide if your page should have the FAQ schema SERP feature. Generally it only shows if you’re in the top 10 results for a query, and don’t have another page feature such as the snippet.

Here’s a nice example from some guy who cheekily has FAQ schema on his post about FAQ schema:

FAQ schema example

Links are show as raw HTML when you lint the page, but will show up as functional and useful links when output in the SERP:

FAQ schema link example

You can also use HTML markup for bold, italics, headers, etc. to structure your result. However, I would caution against this since having a blog post embedded in the SERP is kind of a weird user experience, and likely to get demoted by the big G in the future.

I find that it’s best to use them for “quick tips” and facts, and give the reader a little tease about why they should read your post. Smash Digital has a really good guide on CTR for FAQ schema, if you want to read more on the topic.

As always, if you think there is a better way to do this, contact me at jameson [at] jamesonzimmer [dot] com and I’ll update the post if you’re correct!