jekyll-ai-visible-content 0.1.0

data/lib/jekyll_ai_visible_content/json_ld/collection_schema.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module JsonLd
+    class CollectionSchema
+      attr_reader :config, :page, :items
+
+      def initialize(config, page, items)
+        @config = config
+        @page = page
+        @items = items
+      end
+
+      def build
+        return nil unless items&.any?
+
+        {
+          '@type' => 'CollectionPage',
+          'name' => page.data['title'],
+          'description' => page.data['description'],
+          'url' => absolute_url(page.url),
+          'mainEntity' => {
+            '@type' => 'ItemList',
+            'itemListElement' => items.each_with_index.map { |item, i| list_item(item, i) }
+          }
+        }.compact
+      end
+
+      private
+
+      def list_item(item, index)
+        {
+          '@type' => 'ListItem',
+          'position' => index + 1,
+          'url' => absolute_url(item.url),
+          'name' => item.data['title']
+        }.compact
+      end
+
+      def absolute_url(path)
+        return path if path&.start_with?('http')
+
+        "#{config.site_url}#{path}"
+      end
+    end
+  end
+end

data/lib/jekyll_ai_visible_content/json_ld/faq_schema.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module JsonLd
+    class FaqSchema
+      attr_reader :config, :page
+
+      def initialize(config, page)
+        @config = config
+        @page = page
+      end
+
+      def build
+        faq_items = page.data['faq']
+        return nil unless faq_items&.any?
+
+        {
+          '@type' => 'FAQPage',
+          'mainEntity' => faq_items.map { |item| build_question(item) }
+        }
+      end
+
+      private
+
+      def build_question(item)
+        {
+          '@type' => 'Question',
+          'name' => item['question'],
+          'acceptedAnswer' => {
+            '@type' => 'Answer',
+            'text' => item['answer']
+          }
+        }
+      end
+    end
+  end
+end

data/lib/jekyll_ai_visible_content/json_ld/how_to_schema.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module JsonLd
+    class HowToSchema
+      attr_reader :config, :page
+
+      def initialize(config, page)
+        @config = config
+        @page = page
+      end
+
+      def build
+        how_to = page.data['how_to']
+        return nil unless how_to
+
+        data = {
+          '@type' => 'HowTo',
+          'name' => how_to['name']
+        }
+
+        data['totalTime'] = how_to['total_time'] if how_to['total_time']
+        data['step'] = build_steps(how_to['steps']) if how_to['steps']&.any?
+
+        data.compact
+      end
+
+      private
+
+      def build_steps(steps)
+        steps.each_with_index.map do |step, idx|
+          {
+            '@type' => 'HowToStep',
+            'position' => idx + 1,
+            'name' => step['name'],
+            'text' => step['text']
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/jekyll_ai_visible_content/json_ld/person_schema.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module JsonLd
+    class PersonSchema
+      attr_reader :config, :registry
+
+      def initialize(config, registry)
+        @config = config
+        @registry = registry
+      end
+
+      def build
+        registry.primary_entity_hash
+      end
+    end
+  end
+end

data/lib/jekyll_ai_visible_content/json_ld/website_schema.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module JsonLd
+    class WebsiteSchema
+      attr_reader :config, :registry
+
+      def initialize(config, registry)
+        @config = config
+        @registry = registry
+      end
+
+      def build
+        data = {
+          '@type' => 'WebSite',
+          '@id' => "#{config.site_url}/#website",
+          'url' => config.site_url,
+          'name' => config.site_title,
+          'description' => config.site_description&.strip,
+          'publisher' => registry.primary_entity_ref
+        }
+
+        append_search_action(data)
+        data.compact
+      end
+
+      private
+
+      def append_search_action(data)
+        search_url = "#{config.site_url}/search?q={search_term_string}"
+        data['potentialAction'] = {
+          '@type' => 'SearchAction',
+          'target' => search_url,
+          'query-input' => 'required name=search_term_string'
+        }
+      end
+    end
+  end
+end

data/lib/jekyll_ai_visible_content/tags/ai_author_tag.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module Tags
+    class AiAuthorTag < Liquid::Tag
+      def render(context)
+        site = context.registers[:site]
+        config = JekyllAiVisibleContent.config(site)
+        return '' unless config.enabled?
+
+        entity = config.entity
+        return '' unless entity['name']
+
+        parts = []
+        parts << %(<span itemprop="author" itemscope itemtype="https://schema.org/Person">)
+        parts << %(  <a itemprop="url" href="#{config.site_url}/about/">)
+        parts << %(    <span itemprop="name">#{entity['name']}</span>)
+        parts << %(  </a>)
+        parts << %(</span>)
+        parts.join("\n")
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('ai_author', JekyllAiVisibleContent::Tags::AiAuthorTag)

data/lib/jekyll_ai_visible_content/tags/ai_breadcrumb_tag.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module Tags
+    class AiBreadcrumbTag < Liquid::Tag
+      def render(context)
+        site = context.registers[:site]
+        page = context.registers[:page]
+        config = JekyllAiVisibleContent.config(site)
+        return '' unless config.enabled? && config.json_ld['include_breadcrumbs']
+
+        url = page['url'] || '/'
+        segments = url.to_s.split('/').reject(&:empty?)
+        return '' if segments.empty?
+
+        items = [breadcrumb_item('Home', "#{config.site_url}/")]
+
+        path = ''
+        segments.each_with_index do |segment, idx|
+          path = "#{path}/#{segment}"
+          name = if idx == segments.size - 1
+                   page['title'] || humanize(segment)
+                 else
+                   humanize(segment)
+                 end
+
+          items << if idx == segments.size - 1
+                     %(<li><span aria-current="page">#{name}</span></li>)
+                   else
+                     breadcrumb_item(name, "#{config.site_url}#{path}/")
+                   end
+        end
+
+        %(<nav aria-label="Breadcrumb"><ol>#{items.join}</ol></nav>)
+      end
+
+      private
+
+      def breadcrumb_item(name, url)
+        %(<li><a href="#{url}">#{name}</a></li>)
+      end
+
+      def humanize(slug)
+        slug.gsub(/[-_]/, ' ').gsub(/\b\w/, &:upcase)
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('ai_breadcrumbs', JekyllAiVisibleContent::Tags::AiBreadcrumbTag)

data/lib/jekyll_ai_visible_content/tags/ai_entity_link_tag.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module Tags
+    class AiEntityLinkTag < Liquid::Tag
+      SYNTAX = /\A\s*"([^"]+)"\s*\z/
+
+      def initialize(tag_name, markup, tokens)
+        super
+        match = markup.match(SYNTAX)
+        @entity_name = match ? match[1] : markup.strip.delete('"')
+      end
+
+      def render(context)
+        site = context.registers[:site]
+        config = JekyllAiVisibleContent.config(site)
+        return @entity_name unless config.enabled?
+
+        registry = Entity::Registry.new(config)
+        definition = registry.find_entity_by_name(@entity_name)
+
+        if definition
+          url = definition['url']
+          build_link(url, @entity_name)
+        else
+          @entity_name
+        end
+      end
+
+      private
+
+      def build_link(url, name)
+        %(<a href="#{url}" itemprop="about" itemscope itemtype="https://schema.org/Thing">) +
+          %(<span itemprop="name">#{name}</span></a>)
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('ai_entity_link', JekyllAiVisibleContent::Tags::AiEntityLinkTag)

data/lib/jekyll_ai_visible_content/tags/ai_json_ld_tag.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module Tags
+    class AiJsonLdTag < Liquid::Tag
+      def render(context)
+        site = context.registers[:site]
+        page = context.registers[:page]
+        config = JekyllAiVisibleContent.config(site)
+        return '' unless config.enabled?
+
+        registry = Entity::Registry.new(config)
+        builder = JsonLd::Builder.new(config, registry)
+
+        page_obj = find_page_object(site, page)
+        return '' unless page_obj
+
+        nodes = if homepage?(page)
+                  builder.build_for_homepage
+                else
+                  builder.build_for_page(page_obj)
+                end
+
+        return '' if nodes.empty?
+
+        skip_types = seo_tag_types(config)
+        nodes.reject! { |n| skip_types.include?(n['@type']) } if skip_types.any?
+
+        builder.to_script_tag(nodes)
+      end
+
+      private
+
+      def homepage?(page)
+        url = page['url'] || page['permalink']
+        ['/', '/index.html'].include?(url)
+      end
+
+      def find_page_object(site, page_hash)
+        url = page_hash['url'] || page_hash['permalink']
+        site.posts.docs.find { |p| p.url == url } ||
+          site.pages.find { |p| p.url == url }
+      end
+
+      def seo_tag_types(config)
+        return [] unless config.seo_tag_present?
+
+        %w[WebSite]
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('ai_json_ld', JekyllAiVisibleContent::Tags::AiJsonLdTag)

data/lib/jekyll_ai_visible_content/tags/ai_related_posts_tag.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module Tags
+    class AiRelatedPostsTag < Liquid::Tag
+      LIMIT_SYNTAX = /limit\s*:\s*(\d+)/
+
+      def initialize(tag_name, markup, tokens)
+        super
+        match = markup.match(LIMIT_SYNTAX)
+        @limit = match ? match[1].to_i : nil
+      end
+
+      def render(context)
+        site = context.registers[:site]
+        page = context.registers[:page]
+        config = JekyllAiVisibleContent.config(site)
+        return '' unless config.enabled? && config.linking['enable_related_posts']
+
+        limit = @limit || config.linking['related_posts_limit'] || 3
+        page_obj = find_page_object(site, page)
+        return '' unless page_obj
+
+        related = find_related(site, page_obj, limit)
+        return '' if related.empty?
+
+        render_html(related)
+      end
+
+      private
+
+      def find_page_object(site, page_hash)
+        url = page_hash['url']
+        site.posts.docs.find { |p| p.url == url } || site.pages.find { |p| p.url == url }
+      end
+
+      def find_related(site, current, limit)
+        explicit = current.data['related_slugs']
+        if explicit&.any?
+          posts = explicit.filter_map do |slug|
+            site.posts.docs.find { |p| p.data['slug'] == slug || p.url.include?(slug) }
+          end
+          return posts.first(limit) if posts.any?
+        end
+
+        scored = site.posts.docs.reject { |p| p.url == current.url }.map do |post|
+          score = jaccard_similarity(current.data['tags'] || [], post.data['tags'] || []) * 3
+          score += jaccard_similarity(current.data['categories'] || [], post.data['categories'] || []) * 2
+          score += jaccard_similarity(current.data['topics'] || [], post.data['topics'] || [])
+          [post, score]
+        end
+
+        scored.select { |_, s| s.positive? }.sort_by { |_, s| -s }.first(limit).map(&:first)
+      end
+
+      def jaccard_similarity(set_a, set_b)
+        a = set_a.map(&:to_s).map(&:downcase)
+        b = set_b.map(&:to_s).map(&:downcase)
+        intersection = (a & b).size.to_f
+        union = (a | b).size.to_f
+        union.zero? ? 0.0 : intersection / union
+      end
+
+      def render_html(posts)
+        lines = []
+        lines << '<nav aria-label="Related posts">'
+        lines << '  <h2>Related Posts</h2>'
+        lines << '  <ul>'
+
+        posts.each do |post|
+          lines << '    <li itemscope itemtype="https://schema.org/BlogPosting">'
+          lines << "      <a itemprop=\"url\" href=\"#{post.url}\">"
+          lines << "        <span itemprop=\"headline\">#{post.data['title']}</span>"
+          lines << '      </a>'
+          if post.data['date']
+            dt = post.data['date'].strftime('%Y-%m-%d')
+            published = post.data['date'].strftime('%b %d, %Y')
+            lines << "      <time itemprop=\"datePublished\" datetime=\"#{dt}\">#{published}</time>"
+          end
+          lines << '    </li>'
+        end
+
+        lines << '  </ul>'
+        lines << '</nav>'
+        lines.join("\n")
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('ai_related_posts', JekyllAiVisibleContent::Tags::AiRelatedPostsTag)

data/lib/jekyll_ai_visible_content/validators/entity_consistency_validator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module Validators
+    class EntityConsistencyValidator
+      attr_reader :config, :site
+
+      def initialize(config, site)
+        @config = config
+        @site = site
+      end
+
+      def validate
+        warnings = []
+
+        warnings.concat(check_name_consistency) if config.validation['warn_name_inconsistency']
+        warnings.concat(check_missing_same_as) if config.validation['warn_missing_same_as']
+        warnings.concat(check_missing_dates) if config.validation['warn_missing_dates']
+        warnings.concat(check_missing_descriptions) if config.validation['warn_missing_descriptions']
+        warnings.concat(check_generic_titles)
+
+        warnings
+      end
+
+      private
+
+      def check_name_consistency
+        warnings = []
+        canonical = config.entity['name']
+        return warnings unless canonical
+
+        author_config = site.config['author']
+        site_author = author_config.is_a?(Hash) ? author_config['name'] : author_config
+        if site_author.is_a?(String) && site_author != canonical
+          warnings << "Name inconsistency: site.author='#{site_author}' differs from entity.name='#{canonical}'"
+        end
+
+        site.posts.docs.each do |post|
+          author = post.data['author']
+          next unless author.is_a?(String) && author != canonical
+
+          warnings << "Name inconsistency in #{post.relative_path}: author='#{author}' differs from '#{canonical}'"
+        end
+
+        warnings
+      end
+
+      def check_missing_same_as
+        same_as = config.entity['same_as']
+        return [] if same_as&.any?
+
+        ['Entity has no sameAs links to external profiles (LinkedIn, GitHub, etc.)']
+      end
+
+      def check_missing_dates
+        warnings = []
+        site.posts.docs.each do |post|
+          next if post.data['last_modified_at']
+
+          warnings << "Missing last_modified_at in #{post.relative_path} (freshness scoring disabled)"
+        end
+        warnings
+      end
+
+      def check_missing_descriptions
+        warnings = []
+        all_docs.each do |doc|
+          next if doc.data['description'] && !doc.data['description'].to_s.strip.empty?
+
+          warnings << "Missing description in #{doc.respond_to?(:relative_path) ? doc.relative_path : doc.url}"
+        end
+        warnings
+      end
+
+      def check_generic_titles
+        warnings = []
+        generic = %w[about blog home page post]
+
+        all_docs.each do |doc|
+          title = doc.data['title'].to_s.strip.downcase
+          next unless generic.include?(title)
+
+          path = doc.respond_to?(:relative_path) ? doc.relative_path : doc.url
+          warnings << "Generic title '#{doc.data['title']}' in #{path} (include entity name for discoverability)"
+        end
+        warnings
+      end
+
+      def all_docs
+        site.posts.docs + site.pages
+      end
+    end
+  end
+end

data/lib/jekyll_ai_visible_content/validators/json_ld_validator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module Validators
+    class JsonLdValidator
+      REQUIRED_PERSON_FIELDS = %w[@type @id name].freeze
+      REQUIRED_POSTING_FIELDS = %w[@type headline author].freeze
+
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      def validate
+        errors = []
+        errors.concat(validate_entity_config)
+        errors
+      end
+
+      def validate_node(node)
+        errors = []
+        return errors unless node.is_a?(Hash)
+
+        case node['@type']
+        when 'Person'
+          errors.concat(validate_fields(node, REQUIRED_PERSON_FIELDS, 'Person'))
+        when 'BlogPosting'
+          errors.concat(validate_fields(node, REQUIRED_POSTING_FIELDS, 'BlogPosting'))
+        end
+
+        errors
+      end
+
+      private
+
+      def validate_entity_config
+        errors = []
+        entity = config.entity
+
+        unless entity['name'] && !entity['name'].strip.empty?
+          errors << 'Entity name is required in ai_visible_content.entity.name'
+        end
+
+        if entity['id_slug'].nil? && entity['name'].nil?
+          errors << 'Entity requires either id_slug or name to generate @id'
+        end
+
+        errors
+      end
+
+      def validate_fields(node, required, type_name)
+        missing = required.select { |f| node[f].nil? || node[f].to_s.strip.empty? }
+        missing.map { |f| "#{type_name} JSON-LD missing required field: #{f}" }
+      end
+    end
+  end
+end

data/lib/jekyll_ai_visible_content/validators/link_validator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  module Validators
+    class LinkValidator
+      attr_reader :config, :site
+
+      def initialize(config, site)
+        @config = config
+        @site = site
+      end
+
+      def validate
+        warnings = []
+        warnings.concat(check_orphan_pages) if config.validation['warn_orphan_pages']
+        warnings
+      end
+
+      private
+
+      def check_orphan_pages
+        orphans = site.data['ai_orphan_pages'] || []
+        orphans.map { |url| "Orphan page (no inbound links): #{url}" }
+      end
+    end
+  end
+end

data/lib/jekyll_ai_visible_content/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JekyllAiVisibleContent
+  VERSION = '0.1.0'
+end