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":"https://schema.org","@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:

<hr>
<h2>Frequently Asked Questions</h2>
{% for item in page.faq %}
<h3>{{item.question}}</h3>
<p>{{item.answer}}</p>
{% 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"
faq: 
- question: "How do I add FAQ schema to my Jekyll site?"
  answer: "simply read Jameson's <a href='https://jamesonzimmer.com/faq-schema-jekyll-liquid/'>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.

Caveats

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

• Don’t use emojis. Using emojis to make your result look pretty or “verified” has been abused to the point that pages with emojis in FAQ schema are likely to be invalidated for the feature.
• Do use markup and links. Adding links to your FAQ schema is totally legitimate and is a great way to direct people to the most relevant page on your site. For example, if someone searches “how to hire a plumber in LA” and your plumbing site post on “how to vet a plumbing service in LA” shows up, a FAQ schema item addressing “who are the most popular plumbers in LA” linking to your “best plumbers in Los Angeles” page would be helpful for the user intent. Adding a “how to get a quote for X” item to your company homepage would also be perfectly legitimate.

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:

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:

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!

There are some plugins floating around GitHub for this purpose, but I wanted to accomplish it with Liquid templating only if possible. So, this solution is Liquid-only and should work fine with GitHub Pages (which doesn’t allow Jekyll plugins at this time).

Goal: Dynamic Footnotes in Markdown

My goal was to be able to type footnotes and references into my text, but without numbering them, so that I could move or add/remove citations without disrupting the numbering.

Basically, I wanted something like this:

Here is some text in a blog post. [^footnote]  
[^footnote]: Here is the footnote, with citation or commentary. 

Here is another sentence. [^footnote]  
[^footnote]: here is another footnote. 

Rather than the Markdown norm for footnotes, which looks like this:

Here is some text in a blog post. [^1]  
[^1]: Here is the footnote, with citation or commentary. 

Here is another sentence. [^2]  
[^2]: here is another footnote. 

…And have the output HTML still result in numbered footnotes like this:

<p>Here is some text in a blog post.<sup id="fnref:1"><a href="#fn:1" class="footnote">1</a></sup></p>

<p>Here is another sentence.</p><sup id="fnref:2"><a href="#fn:2" class="footnote">2</a></sup></p>

<div class="footnotes">
  <ol>
    <li id="fn:1">
      <p>Here is the footnote, with citation or commentary. <a href="#fnref:1" class="reversefootnote">&#8617;</a></p>
    </li>
    <li id="fn:2">
      <p>here is another footnote. <a href="#fnref:2" class="reversefootnote">&#8617;</a></p>
    </li>
  </ol>
</div>

Solution: Increment Counter in Liquid

The solution I came up with is to increment a counter in Liquid (template language used by Jekyll):

<!-- Define ref at top of post  -->
{% assign ref = 1 %}

<!-- Include counter with each reference -->
Here is some text in a blog post. [^{{ref}}]  
[^{{ref}}]: Here is the footnote, with citation or commentary.  
{% assign ref = ref | plus:1 %}

Here is another sentence. [^{{ref}}]  
[^{{ref}}]: here is another footnote.  
{% assign ref = ref | plus:1 %}

This solution is a bit clunky, but works for me. I also like that it works for loops on data in my site, which is a regular use case for my project:

<!-- Define ref at top of post  -->
{% assign ref = 1 %}

Some manually written text leading into a listicle based on CSV in the site.data file: 

<!-- Include counter with each for loop -->
{% for item in site.data.my-special-data %}
## {{ item.title }}  
{{ item.text }} {% if item.footnote %}[^{{ref}}]

[^{{ref}}]: {{item.footnote}}
{% assign ref = ref | plus:1 %}
{% endif %}
{% endfor %}

…and the counter just picks up again when you continue with manually written content after the Liquid loop on your data file(s).

Tell me the better way

Anyway, I hope this solution is useful to folks like myself with limited development skills but a stubborn desire to use minimalist tools like Jekyll/GitHub Pages.

If you’re reading this and you think this is a bad solution, please email me and tell me: jameson [at] jamesonzimmer [dot] com. I’ll update the page or just redirect if there is a better solution.

In Jekyll, those dependency issues usually relate to Bundler, the tool of choice for managing the gems, Ruby versions, and other “dependencies” needed to run your site.

If you’re reading this post, you probably are Googling a Terminal error related to “invalid date” for your Jekyll site… even though all the dates in your _posts folder appear to be properly structured. (YYYY-MM-DD-title-of-post.md.)

It probably looks something like this:

` Error: could not read file [PATH TO YOUR PROJECT]/vendor/bundle/ruby/2.5.0/gems/jekyll-3.8.5/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb: Invalid date ‘<%= Time.now.strftime(‘%Y-%m-%d %H:%M:%S %z’) %>’: Document ‘vendor/bundle/ruby/2.5.0/gems/jekyll-3.8.5/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb’ does not have a valid date in the YAML front matter. ERROR: YOUR SITE COULD NOT BE BUILT: ———————————— Invalid date ‘<%= Time.now.strftime(‘%Y-%m-%d %H:%M:%S %z’) %>’: Document ‘vendor/bundle/ruby/2.5.0/gems/jekyll-3.8.5/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb’ does not have a valid date in the YAML front matter. `

You’re probably seeing this issue because your vendor folder is being included in your _site folder, which is the “production” folder for your website. Vendor is meant to be read by Jekyll, but is not meant to be shown to the public on your server. If the vendor folder is included, you are likely to see errors because Jekyll thinks you want the files included in vendor to be interpreted as production files.

Disclaimer: I am not a developer, and I use Jekyll as an amateur who just appreciates the simplicity of the tool. There are probably more elegant ways to address this error, which involve re-configuring your rbenv or Bundler setup.

However, the simplest way I’ve found to deal with this error is to simply exclude the vendor folder from my Jekyll build, which seems like good practice anyway since I can’t imagine why those files would be needed within the static assets I’m deploying with Netlify, AWS, GitHub Pages, or what have you.

How to fix “invalid date” Jekyll vendor/bundle/ruby issue

The solution is to “exclude” vendor folder from _site

Inside your config file, search for the “exclude” line. There are a few ways to format it, but it probably looks like this:

Or like this:

Go ahead and exclude vendor like this:

exclude: - vendor

or:

exclude: ['vendor']

Note that if you have existing “excludes” in your Jekyll project (which is likely if you’re working off a theme you downloaded from somewhere), you need to add the vendor file to exlude list, not create a new exclude line within your config file.

However, I found this book engaging because it had a fresh and helpful perspective on my field of work — digital content and search — that I would never get from results-obsessed and ethics-free industry publications.

This post will be less a review of the book and more a catalog of the parts I found relevant for understanding the practical side of search and digital media.

Elemental Media and Search Engine Optimization

Peter’s description of the mechanisms underpinning Google’s search algorithm brings up a parallel between another problematic system of determining value: the academic publishing industry.

The reading logic of PageRank, which mimics the academic prestige system, is another way in which Google ties to campus culture. “Publish or perish” is the famous rule for university professors, but the calculus is actually more subtle. Professors love to read; and even more, they love to write. Even more than writing, they love to publish. But even more than publishing, they love to be read. Better than being read is being cited. Even better than being cited, however, is being cited by someone important. And how do you know who is important? By citations, of course: an important scholar gets cited a lot. Scholars who are cited by other scholars a lot confer greater authority when they cite another scholar: they channel the power of their inlinks.

I hadn’t considered this parallel before. It’s a helpful tool for thinking about issues with search. How do you account for valuable content that isn’t heavily linked? How do you avoid rewarding sites/scholars who game the system, especially when the system is largely automated and rewards volume of engagement over accuracy?

Another gem that says volumes about the search industry:

The art of searching, like that of fire, consists largely in elimination.

Peters is quick to compare digital archives to endless graveyards, less prone to considering them as living media.

Of course, the vast majority of content on the Internet is not valuable to anybody. There are reams of evidence showing how pages that fall below the top ten results are essentially archived — rarely read, and then only by niche researchers. To what degree is the volume of engaged content related to the value of the content, and to what degree is it defined by the “top ten” parameters of the Google search design?

Google has been testing infinite scroll results on mobile as of 2018, which could heavily impact the distribution of traffic in the top of the search results iceberg.

In practice, Google tends to prefer paginated content in their own UX as well as sites being ranked, since infinite scrolls are complex to catalog compared to neat, orderly books.

Ironically, Chrome manages the loading of infinitely scrolled content using a technique called “tombstones”.

Culture shaping media, media shaping culture

Peters presents a Borgesian “map and territory” dilemma throughout the book, made particularly clear in the sections on digital media and search:

[T]he aim [of PageRank] is not to know every square inch of soil but to figure out topography from the water flows. More simply, the content of documents can be inferred from their location in networks.

Engaging with digital media, people and algorithms alike are faced with the challenge of prioritizing information in a “library of Babel” of our own making.

How long is the coast of England? The answer to this last question famously depends on the length of the measuring stick: the shorter the stick, the more it can account for small squiggles of shape, and thus longer the measured length.

The more accurate the map, the more the map “becomes” the territory. But really, the representation and abstraction of the real thing is all that’s available to our comprehension — as well as the comprehension of human-designed algorithms.

Visions of the Internet

At one point in the book, Peters describes the three “visions” of digital media proposed by the major FANG companies:

• Google: open field to be surveyed
• Facebook: beehive
• Apple: walled garden

[Google] sees the Internet as an open field to be surveyed rather than as either a social hive or a walled garden (the rival visions of Facebook and Apple).

Internet as environment

The point of The Marvelous Clouds, to the degree that points are possible in academic books of philosophy, is that media is an environment. Like an environment, it is as much shaped as a shaper of those that inhabit it.

Peters suggests that the Internet isn’t really that special — it’s just an extension of existing modes of understanding the world. It suffers from the same issues as traditional media and environments. It is only revolutionary in that it allows for bigger graveyards and magnified bias.

By extension, search and our systems for cataloging a system are unlikely to rise above existing limitations to understanding and organization.

Unfortunately, it’s not that simple, and this sort of “cold turkey” advice tends to come from wealthy, well-positioned older people who can afford to forego the clear social advantages of networking on social media platforms. 

Speaking personally, I’ve used Facebook to find multiple apartments that were cheaper and better suited to me than I could have found on craigslist or through paper ads. Looking at creative fields, it’s hard for an artist to skip out on Instagram and all the potential fans. 

The problem, of course, comes when the tool stops being used for practical gain and starts being used as a time waster.  To respond, I wanted to share a lighter, more realistic alternative. Take action on these three simple changes to your accounts, and you can have 80% of the mental benefits with 20% of the practical sacrifice. 

1. Set all feeds to chronological order. If the platform you’re using doesn’t offer chronological order, consider deleting it. 
2. Block feeds, unless reading and reacting to every post by your social group is essential to your finances or wellbeing. 
3. If you’re using a social platform for personal gain, be strategic about it. For example, I mainly keep Facebook because I occasionally find it useful to ask my social group for leads on practical matters. (Finding apartment, who can sell me a used bike, etc.) To make sure my posts get maximum exposure, I post something I know will get comments every few months so that the Facebook algorithm will see all the engagements on my sporadic posts, and assign my less interesting “who can loan me x” posts more value and exposure. 

One more interesting point from the book worth remembering: 

Lanier claims that AI is being oversold, describing the hype as “AI storytelling.” I can’t speak to the truth of this from experience, but I can point out that even Google’s notoriously secretive and advanced search algorithm relies on armies of (presumably low-paid) search evaluators to make more nuanced decisions about who deserves the coveted top ten spots, following a decidedly analog bible of guidelines that seems built to print out and plunk on a cubicle desk.

I’m not deeply familiar with how DNS settings work, and this is probably the case for many people migrating away from Gmail surveillance to a more private email setup. Eventually I figured it out, so I figured I should post my findings for other people who, like myself, aren’t deeply familiar with the nuts and bolts of DNS and just want to follow a step-by-step setup.

Note that these instructions are for Namecheap-hosted domains for Fastmail email service only. Fastmail already has setup options for Google Suite and Zoho email addresses at custom domains that are documented well on their site. These instructions are only for nameservers hosted with Namecheap, which requires you to point MX records to FastMail.

1. Add your custom domain in the Fastmail domain settings.
2. Configure Namecheap DNS for your custom domain.
3. Check that Fastmail domain settings for confirmation that everything is set up properly.

Add your custom domain in the Fastmail domain settings

Mail > Settings > Domains.

If you signed up for Fastmail with a custom domain, this should already be entered automatically. I will look like this (except without the “MX records set” text.):

If your custom domain is not automatically entered, simply click the “Add Domain” button and enter your custom domain like this:

yourdomain.com

Configure Namecheap DNS for your custom domain.

There are two steps to the process of configuring your DNS records in the Namecheap dashboard for Fastmail.

1. Set MX records for domain
2. Set Host records for domain

Both of these DNS settings can be found in the “advanced DNS” section when managing your Namecheap domains.

Setting up MX records

Sign into your Namecheap account and navigate to the “Advanced DNS” settings for you domain:

Domain List > yourdomain.com MANAGE button > Advanced DNS

Scroll down the page and you’ll see a “Mail Settings” section. Click the dropdown menu and select “Custom MX.” (Highlighted in screenshot below.)

Here are the entries you will need to add:

Note that the . at the end of the value entries is required, but Namecheap will add it automatically if you don’t add period at the end.

When you have set this up properly, it should look exactly like this:

Setting up Host records

Fastmail will work with only MX records set. However, they recommend setting up SPF and DKIM as well to ensure your emails send properly and are not marked as spam.

Without getting too technical, here are the reasons why you should bother with this step:

• SPF: SPF (Sender Policy Framework) was a method of preventing email spoofing that never really worked that well. Unfortunately, some email clients see SPF failures as a sign of spam. Basically, you should set SPF so that other email clients don’t interpret your emails as spam and send them to the spam folder.
• DKIM: DKIM (Domainkeys Identified Email) is a way of associating or “signing” your email with your domain rather than the generic “messagingingine.com” domain. If you don’t set up DKIM, emails you send to Gmail addresses will display a “sent via messagingenging.com” warning next to your email that makes it appear suspicious.

To set these up, you’ll need to add the following records to the “Host Records” section of your Namecheap “Advanced DNS” area (Replace “yourdomain.com” with your domain):

When finished, it should look something like this:

Check everything is working

Finally, the last step is to make sure Fastmail is seeing your DNS updates and confirm everything is working as intended.

Settings > Domains > Edit

You should see three big green checkmarks for each of the items you just completed:

Within a few minutes (up to a few hours in some cases) you should be able to send and receive emails with any other address, and your emails should display in recipient inboxes with no flags or warnings. In my case, everything was working within ten minutes.

Feel free to send an email to me at jameson@jamesonzimmer.com if you want to test your new Fastmail/Namecheap address!

It came to my attention recently that iA Writer has made their iA Writer Duospace font available freely on GitHub.

This is a beautiful and practical font for composition, based loosely on the iconic open-source IBM Plex fontface. It’s somewhere in between a monospace and proportional font:

In theory, monospace fonts are best for composition because they force you to slow down when reading and have a “raw” look that suits the separation of content and presentation. In practice (and my opinion), monospace becomes sort of grating to look at for hours on end.

If you like the aesthetic of iA Writer but prefer Ulysses for usability reasons, using the Duospace font in Ulysses will make it look almost identical:

All you have to do is add the iA Writer Duospace font as a system font on your Mac:

1. Download the font files (.otf) for Mac.
2. Open the Go menu option and hold down the Alt/Option key. The Library option will appear. This is hidden by default.
3. Open the library folder, and navigate from Library > Fonts
4. Drop all four .otf Duospace files into the folder.
5. Open Ulysses and navigate to Preferences > General, click the font button and select “Custom” at the bottom of the munu.
6. Select iA Writer Duospace Regular.

using the Yosemite Ulysses theme and the Duospace font, you should be left with a pleasant minimal workspace for composition that looks like iA Writer, but functions like Ulysses.

• two post types: text, pdf
• multiple non-technical contributors
• prose.io CMS
• Github hosted

The final solution I came up with results in a page that looks like this:

Because they would be updating via prose.io rather than a local machine, I needed a way to embed them from somewhere other than GitHub, which doesn’t seem really optimized for that sort of file anyway.

There are some services out there for this and among them Issuu came closest to offering what we needed. However, their free tier injects ads into the iframe, and anyway all the features seemed like overkill for just displaying a pdf.

The best solution I could find was sort of a hack, embedding them as publicly shared files from Google Drive.

Setting up a pdf layout in Jekyll

So first let’s set up a new layout, pdf.html, within _layouts:

Note that if your CSS sets the body width to less than 100%, the embed won’t be full-screen like in my example.

Getting the embed code, copying and pasting

The process is:

1. upload pdf to google drive
2. make pdf public
3. copy embed code
4. paste into post
5. change inline width and height values to 100%

So once that’s set up, adding pdfs to the site is just a question of uploading to google docs and getting the embed code. The important thing here is to make sure the file’s sharing settings are set to “public”. Here’s a screencast showing where all the buttons are:

Drop that into your post, change the default width and height values to 100%, and you should have a file that looks something like this:

Perhaps there are more elegant solutions out there, but this is pretty straightforward, simple, free, and it works. Source available on GitHub if you’re curious.

I’m not super proud of this repository in hindsight, but have received some nice emails thanking me for this solution so figured I should leave it up as a public service.