jekyll-structured-content

A lightweight Jekyll plugin for structured data helpers in content-driven Jekyll sites.

• FAQPage JSON-LD generation
• JSON-LD helpers for posts, pages, and project-like content

Scope

This package is intentionally narrow. It focuses on generating clean, reusable structured output from frontmatter and templates without prescribing site copy, citation systems, or a full SEO strategy.

Who this is for

This plugin is for people who:

• publish articles or reference content with Jekyll
• want cleaner machine-readable structured data
• prefer to keep visible theme markup in the site itself
• want a small plugin instead of a full SEO framework

Features

1. Emit FAQPage JSON-LD from FAQ frontmatter.
2. Emit JSON-LD for post, page, and project-like content via a Liquid tag.
3. Leave visible FAQ and theme markup to the site.

What this plugin does not do

• It does not render your visible FAQ accordion or theme markup.
• It does not manage page titles, meta descriptions, or Open Graph tags.
• It does not integrate with citation or bibliography plugins.
• It does not replace a full SEO plugin.

GitHub Pages compatibility

This plugin is compatible with Jekyll sites deployed to GitHub Pages when the site is built through a custom GitHub Actions workflow.

It should not be described as compatible with the default GitHub Pages safe-mode build, because custom plugins are not loaded there.

Installation

Add the gem to your Gemfile:

gem "jekyll-structured-content"

Then add it to _config.yml:

plugins:
  - jekyll-structured-content

Usage

FAQ JSON-LD

<script type="application/ld+json">{% faq_json_ld %}</script>

This reads from page frontmatter like:

faq:
  - question: "What is this?"
    answer: "A short answer."
  - question: "Can I use title/description instead?"
    answer: "Yes, FAQ items may also use title/description keys."

Post schema JSON-LD

<script type="application/ld+json">{% schema_json_ld post %}</script>

Page schema JSON-LD

<script type="application/ld+json">{% schema_json_ld page %}</script>

Project schema JSON-LD

<script type="application/ld+json">{% schema_json_ld project %}</script>

What this plugin expects

This plugin works best when your documents include standard Jekyll frontmatter like:

• title
• description
• date for posts
• url
• image
• category
• tags
• faq

At the site level, it looks for these values when available:

• site.data.settings.title
• site.data.settings.logo
• site.data.settings.author.author_name
• site.data.settings.description

If these settings are missing, the plugin falls back where it can, but richer structured output depends on good site metadata.

Output behavior

• faq_json_ld emits a FAQPage
• schema_json_ld post emits a BlogPosting
• schema_json_ld page emits a WebPage, or ProfilePage for /about/
• schema_json_ld project emits a CreativeWork
• optional fields like dateModified are omitted when not present

Live example

Production example using post schema plus FAQPage schema:

• https://jasonchance.com/blog/the-georgia-rural-zone-playbook-how-small-downtowns-stack-three-state-tax-credits/

Tested assumptions

• Jekyll 4.x
• Liquid 4.x
• local Jekyll builds
• GitHub Pages deployments built through GitHub Actions

Development

Install dependencies:

bundle install

Run tests:

ruby -Itest test/faq_json_ld_tag_test.rb
ruby -Itest test/schema_json_ld_tag_test.rb
ruby -Itest test/schema_page_and_project_test.rb
ruby -Itest test/faq_formats_test.rb