jekyll-structured-content 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6bb8d4fb4c737c5628ac46602e10d8d9cff60bd549dd5ae1c37c8539e7326295
+  data.tar.gz: b742f29446ec10f1a052dd730ba7428f5ba39425c9f679fce8f4d1fad4443d27
+SHA512:
+  metadata.gz: acc9cc12cfe3809e578cdb8287e0a4eaf8cef7dfeea33e91b01f8031032ad683f676724d39c6e56658755de9b2db413ee4b40d60c839508af4be050bba4c36ad
+  data.tar.gz: 0d79e70c5fe6397b5270d919963eafe3b62f66e2b397b1e38f4c7c5732fedcd7714e03cd5610293c8ee299f983022307915d651d97cf5873a247bcfc951ffeb7

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.2.0
+
+- Added `schema_json_ld` tag for post, page, and project schema output
+- Added FAQ JSON-LD support
+- Omit optional schema fields like `dateModified` when values are absent
+- Clarified GitHub Pages compatibility caveats
+
+## 0.1.0
+
+- Initial plugin scaffold

data/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Thanks for your interest in improving `jekyll-structured-content`.
+
+## Before submitting changes
+
+1. Keep the scope narrow and focused on structured data helpers.
+2. Avoid adding theme-specific rendering assumptions.
+3. Add or update tests for behavior changes.
+
+## Local development
+
+```bash
+bundle install
+ruby -Itest test/faq_json_ld_tag_test.rb
+ruby -Itest test/schema_json_ld_tag_test.rb
+```
+
+## Design philosophy
+
+- structured data in the plugin
+- visible theme markup in the site
+- explicit behavior over magic

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Chance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# 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`:
+
+```ruby
+gem "jekyll-structured-content"
+```
+
+Then add it to `_config.yml`:
+
+```yml
+plugins:
+  - jekyll-structured-content
+```
+
+## Usage
+
+### FAQ JSON-LD
+
+```liquid
+<script type="application/ld+json">{% faq_json_ld %}</script>
+```
+
+This reads from page frontmatter like:
+
+```yml
+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
+
+```liquid
+<script type="application/ld+json">{% schema_json_ld post %}</script>
+```
+
+### Page schema JSON-LD
+
+```liquid
+<script type="application/ld+json">{% schema_json_ld page %}</script>
+```
+
+### Project schema JSON-LD
+
+```liquid
+<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:
+
+```bash
+bundle install
+```
+
+Run tests:
+
+```bash
+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
+```

data/_includes/jekyll_structured_content/faq.html

@@ -0,0 +1,44 @@
+{% assign faq_items = include.items | default: page.faq | default: site.data.settings.faq.faq_items %}
+{% assign faq_title = include.title %}
+{% assign faq_description = include.description %}
+{% assign faq_enabled = include.enabled %}
+
+{% if faq_enabled == nil %}
+  {% if include.items or page.faq %}
+    {% assign faq_enabled = true %}
+  {% else %}
+    {% assign faq_enabled = site.data.settings.faq.enable %}
+  {% endif %}
+{% endif %}
+
+{% if faq_enabled and faq_items and faq_items.size > 0 %}
+<section class="section faq">
+  <div class="container">
+    <div class="row">
+      <div class="col col-12">
+        {% if faq_title or faq_description %}
+        <div class="section__info">
+          {% if faq_title %}
+            <h2 class="section__title">{{ faq_title }}</h2>
+          {% endif %}
+          {% if faq_description %}
+            <p class="section__description">{{ faq_description }}</p>
+          {% endif %}
+        </div>
+        {% endif %}
+
+        <div class="faq">
+          {% for faq_item in faq_items %}
+          <div class="faq__item" tabindex="0" data-name="closed">
+            <h3 class="faq__title">{{ faq_item.title | default: faq_item.question }}<svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" fill="none"><path fill="var(--heading-font-color)" d="M8.654 1.168a1.153 1.153 0 1 0-2.308 0V6.36H1.154a1.153 1.153 0 1 0 0 2.308h5.192v5.192a1.153 1.153 0 1 0 2.308 0V8.668h5.192c.638 0 1.154-.516 1.154-1.154 0-.639-.516-1.154-1.154-1.154H8.654V1.168Z"/></svg></h3>
+            <div class="faq__description">
+              <p>{{ faq_item.description | default: faq_item.answer }}</p>
+            </div>
+          </div>
+          {% endfor %}
+        </div>
+      </div>
+    </div>
+  </div>
+</section>
+{% endif %}

data/lib/jekyll/structured_content/faq_json_ld_tag.rb

@@ -0,0 +1,54 @@
+require "json"
+
+module Jekyll
+  module StructuredContent
+    class FaqJsonLdTag < Liquid::Tag
+      def render(context)
+        page = context.registers[:page] || {}
+        faq_items = page["faq"]
+
+        return "" unless faq_items.is_a?(Array) && faq_items.any?
+
+        entities = faq_items.filter_map do |item|
+          question = value_for(item, "question", "title")
+          answer = value_for(item, "answer", "description")
+          next unless question && answer
+
+          {
+            "@type" => "Question",
+            "name" => question,
+            "acceptedAnswer" => {
+              "@type" => "Answer",
+              "text" => normalize_text(answer)
+            }
+          }
+        end
+
+        return "" if entities.empty?
+
+        {
+          "@context" => "https://schema.org",
+          "@type" => "FAQPage",
+          "mainEntity" => entities
+        }.to_json
+      end
+
+      private
+
+      def value_for(item, *keys)
+        keys.each do |key|
+          value = item[key] || item[key.to_sym]
+          return value if value && !value.to_s.strip.empty?
+        end
+
+        nil
+      end
+
+      def normalize_text(text)
+        text.to_s.gsub(%r{<[^>]+>}, " ").gsub(/\s+/, " ").strip
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("faq_json_ld", Jekyll::StructuredContent::FaqJsonLdTag)

data/lib/jekyll/structured_content/schema_filters.rb

@@ -0,0 +1,20 @@
+module Jekyll
+  module StructuredContent
+    module SchemaFilters
+      def schema_type_for(input)
+        case input.to_s
+        when "post"
+          "BlogPosting"
+        when "page"
+          "WebPage"
+        when "project"
+          "CreativeWork"
+        else
+          "WebPage"
+        end
+      end
+    end
+  end
+end
+
+Liquid::Template.register_filter(Jekyll::StructuredContent::SchemaFilters)

data/lib/jekyll/structured_content/schema_json_ld_tag.rb

@@ -0,0 +1,185 @@
+require "json"
+
+module Jekyll
+  module StructuredContent
+    class SchemaJsonLdTag < Liquid::Tag
+      def initialize(tag_name, markup, tokens)
+        super
+        @schema_kind = markup.to_s.strip
+      end
+
+      def render(context)
+        page = context.registers[:page] || {}
+        site = context.registers[:site]
+        data = build_schema(@schema_kind, page, site)
+
+        return "" unless data
+
+        data.to_json
+      end
+
+      private
+
+      def build_schema(kind, page, site)
+        case kind
+        when "post"
+          build_post_schema(page, site)
+        when "page"
+          build_page_schema(page, site)
+        when "project"
+          build_project_schema(page, site)
+        else
+          nil
+        end
+      end
+
+      def build_post_schema(page, site)
+        site_title = site_value(site, "data", "settings", "title")
+        author_name = site_value(site, "data", "settings", "author", "author_name") || site_title
+        description = page["description"] || page["excerpt"]
+        image = absolute_url(page["image"], site)
+        tags = page["tags"] || []
+
+        data = {
+          "@context" => "https://schema.org",
+          "@type" => "BlogPosting",
+          "headline" => page["title"],
+          "description" => normalize_text(description),
+          "datePublished" => xmlschema(page["date"]),
+          "mainEntityOfPage" => {
+            "@type" => "WebPage",
+            "@id" => absolute_url(page["url"], site)
+          },
+          "url" => absolute_url(page["url"], site),
+          "articleSection" => page["category"] || "Blog",
+          "keywords" => Array(tags).join(", "),
+          "wordCount" => word_count(page["content"]),
+          "isPartOf" => {
+            "@type" => "Blog",
+            "name" => site_title,
+            "url" => absolute_url("/blog/", site)
+          },
+          "about" => build_about_entities(page),
+          "author" => {
+            "@type" => "Person",
+            "name" => author_name
+          },
+          "publisher" => {
+            "@type" => "Organization",
+            "name" => site_title,
+            "logo" => {
+              "@type" => "ImageObject",
+              "url" => absolute_url(site_value(site, "data", "settings", "logo"), site)
+            }
+          }
+        }
+
+        date_modified = xmlschema(page["last_modified_at"])
+        data["dateModified"] = date_modified if present_value?(date_modified)
+        data["image"] = { "@type" => "ImageObject", "url" => image } if image
+        data
+      end
+
+      def build_page_schema(page, site)
+        site_title = site_value(site, "data", "settings", "title")
+        description = page["description"] || site_value(site, "data", "settings", "description")
+        image = absolute_url(page["image"], site)
+        page_type = page["url"] == "/about/" ? "ProfilePage" : "WebPage"
+
+        data = {
+          "@context" => "https://schema.org",
+          "@type" => page_type,
+          "name" => page["title"],
+          "description" => normalize_text(description),
+          "url" => absolute_url(page["url"], site)
+        }
+
+        data["image"] = { "@type" => "ImageObject", "url" => image } if image
+
+        if page["url"] == "/about/"
+          data["mainEntity"] = {
+            "@type" => "Person",
+            "name" => site_value(site, "data", "settings", "author", "author_name") || site_title,
+            "description" => normalize_text(description),
+            "url" => absolute_url(page["url"], site)
+          }
+        end
+
+        data
+      end
+
+      def build_project_schema(page, site)
+        data = {
+          "@context" => "https://schema.org",
+          "@type" => "CreativeWork",
+          "name" => page["title"],
+          "description" => normalize_text(page["description"] || page["excerpt"]),
+          "url" => absolute_url(page["url"], site)
+        }
+
+        image = absolute_url(page["image"], site)
+        data["image"] = image if image
+        data
+      end
+
+      def build_about_entities(page)
+        entities = []
+
+        entities << { "@type" => "Thing", "name" => page["category"] } if page["category"]
+        Array(page["tags"]).each do |tag|
+          entities << { "@type" => "Thing", "name" => tag }
+        end
+
+        entities
+      end
+
+      def absolute_url(path, site)
+        return nil unless path && site.respond_to?(:config)
+
+        Jekyll::URL.new(
+          template: ":path",
+          placeholders: { path: path.to_s }
+        ).to_s
+
+        base = site.config["url"].to_s.sub(%r{/$}, "")
+        prefix = site.config["baseurl"].to_s
+        normalized_path = path.to_s.start_with?("/") ? path.to_s : "/#{path}"
+        "#{base}#{prefix}#{normalized_path}"
+      end
+
+      def xmlschema(value)
+        return nil unless value.respond_to?(:xmlschema)
+
+        value.xmlschema
+      end
+
+      def present_value?(value)
+        !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
+      end
+
+      def word_count(content)
+        normalize_text(content).split.size
+      end
+
+      def normalize_text(text)
+        text.to_s.gsub(%r{<[^>]+>}, " ").gsub(/\s+/, " ").strip
+      end
+
+      def site_value(site, *keys)
+        current = site
+        keys.each do |key|
+          current =
+            if current.respond_to?(:[])
+              current[key]
+            elsif current.respond_to?(key)
+              current.public_send(key)
+            end
+          return nil if current.nil?
+        end
+        current
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("schema_json_ld", Jekyll::StructuredContent::SchemaJsonLdTag)

data/lib/jekyll/structured_content/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module StructuredContent
+    VERSION = "0.2.0"
+  end
+end

data/lib/jekyll/structured_content.rb

@@ -0,0 +1,9 @@
+require_relative "structured_content/version"
+require_relative "structured_content/faq_json_ld_tag"
+require_relative "structured_content/schema_json_ld_tag"
+require_relative "structured_content/schema_filters"
+
+module Jekyll
+  module StructuredContent
+  end
+end

data/lib/jekyll-structured-content.rb

@@ -0,0 +1,4 @@
+require "jekyll"
+require "liquid"
+
+require_relative "jekyll/structured_content"

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-structured-content
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Jason Chance
+bindir: bin
+cert_chain: []
+date: 2026-08-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: A focused Jekyll plugin for FAQPage JSON-LD and post, page, and project
+  schema helpers.
+email:
+- jchance@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- _includes/jekyll_structured_content/faq.html
+- lib/jekyll-structured-content.rb
+- lib/jekyll/structured_content.rb
+- lib/jekyll/structured_content/faq_json_ld_tag.rb
+- lib/jekyll/structured_content/schema_filters.rb
+- lib/jekyll/structured_content/schema_json_ld_tag.rb
+- lib/jekyll/structured_content/version.rb
+homepage: https://github.com/jchance/jekyll-structured-content
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jchance/jekyll-structured-content
+  source_code_uri: https://github.com/jchance/jekyll-structured-content
+  changelog_uri: https://github.com/jchance/jekyll-structured-content/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Structured data helpers for Jekyll content
+test_files: []