page_structured_data 1.0.13 → 1.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e263a2b3ad541c2b5e72aa79e71d47d72803ddb8a4ac286898e6c6f35105394
-  data.tar.gz: 96f01f8fc820456eb69ba5a351f8971022758088d0a5633240c38c7831df43f9
+  metadata.gz: 1e36ab494ebd4db8743deb6d8415e826c2186f7c28a7e2927c8a08df4decabd6
+  data.tar.gz: b48c8723a6ad4a3ee5aa44be5e6b36d6764abbd433a3daedb1e3278f32cf7b2b
 SHA512:
-  metadata.gz: 802b70166a18b5475e702822cfb7b0c565c7fc59d8dd5059831261676831e1150c95b8f0e1e11b0de493aa120f3e23f2ddd9a619238ebcdd5f25c8f3920d3d6e
-  data.tar.gz: bc818be71ea5d603ac3fb6b84e99dcf79fd76607f3272039cde49d65c772f365d812c0f7d260cdf7beda88762012994ae207b309e7a5dc21b94ab129608e0c9e
+  metadata.gz: 1c9dd473ced4959c0acc17940b212d0c71b760efe3a0cfe119d74845ab10b76e081363b26d4138f6b5d66a5e62d0f7c36623c5603ac78ec8565350e2cd53dbcf
+  data.tar.gz: eefd736852c02d3ec1f02a58e7911f931d8882ce09854364c9b028cd1a11aa1872c3fe1a79beb4c379b8468e1b3db7871a00331dc47522573da9abc64bfa6dce

data/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project are documented here.
 
 ## Unreleased
 
+## 1.0.14 - 2026-07-05
+
+- Add page-level `robots` meta tag support.
+- Add richer optional schema fields for article-like page types.
+- Add README common pattern examples.
+- Add focused rendered metadata output coverage.
+- Add soft validation helpers with `warnings` and `valid?`.
+- Improve README and gem metadata positioning.
+
 ## 1.0.13 - 2026-05-06
 
 - Add `PageStructuredData::PageTypes::Person` for reusable schema.org person values.

data/README.md

@@ -3,7 +3,9 @@
 [![Gem Version](https://badge.fury.io/rb/page_structured_data.svg)](https://rubygems.org/gems/page_structured_data)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](MIT-LICENSE)
 
-PageStructuredData is a small Rails engine for rendering page-level SEO and social sharing metadata from one page object.
+PageStructuredData is a small Rails engine that keeps SEO metadata, social sharing tags, and JSON-LD structured data in one page object and one view partial.
+
+Use it when a Rails app has metadata spread across layouts, helpers, presenters, and page-specific templates. PageStructuredData gives each page one explicit metadata object, then renders the `<title>`, meta tags, Open Graph tags, Twitter Card tags, breadcrumbs, and schema.org JSON-LD consistently.
 
 It helps Rails applications render:
 
@@ -98,7 +100,8 @@ Set `@page_meta` in the controller or view before the layout renders:
   description: "Welcome to my page",
   image: image_url("social/home.png"),
   canonical_url: home_url,
-  fallback_image: image_url("social/default.png")
+  fallback_image: image_url("social/default.png"),
+  robots: "index,follow"
 )
 ```
 
@@ -265,6 +268,182 @@ website_page_type = PageStructuredData::PageTypes::WebSite.new(
 )
 ```
 
+## Common Patterns
+
+### Article Page
+
+Use `BlogPosting` or `NewsArticle` when a page represents editorial content:
+
+```ruby
+publisher = PageStructuredData::PageTypes::Organization.new(
+  name: "Example",
+  url: root_url
+)
+
+author = PageStructuredData::PageTypes::Person.new(
+  name: @article.author.name,
+  url: author_url(@article.author)
+)
+
+article_page_type = PageStructuredData::PageTypes::BlogPosting.new(
+  headline: @article.title,
+  description: @article.summary,
+  article_body: @article.body.to_plain_text,
+  url: article_url(@article),
+  main_entity_of_page: article_url(@article),
+  publisher: publisher,
+  article_section: @article.category.name,
+  keywords: @article.tags.pluck(:name),
+  word_count: @article.word_count,
+  in_language: "en",
+  published_at: @article.published_at,
+  updated_at: @article.updated_at,
+  authors: [author],
+  image: url_for(@article.cover_image),
+  likes_count: @article.likes_count
+)
+
+@page_meta = PageStructuredData::Page.new(
+  title: @article.title,
+  description: @article.summary,
+  image: url_for(@article.cover_image),
+  canonical_url: article_url(@article),
+  breadcrumb: article_breadcrumbs,
+  page_type: article_page_type
+)
+```
+
+### Homepage
+
+Use both `Organization` and `WebSite` when the page represents the public home of a site or organization:
+
+```ruby
+founder = PageStructuredData::PageTypes::Person.new(
+  name: "Jane Doe",
+  url: "https://example.com/jane"
+)
+
+organization = PageStructuredData::PageTypes::Organization.new(
+  name: "Example",
+  url: root_url,
+  description: "Useful software from Example",
+  logo: image_url("logo.png"),
+  same_as: ["https://github.com/example"],
+  founder: founder
+)
+
+website = PageStructuredData::PageTypes::WebSite.new(
+  name: "Example",
+  url: root_url,
+  description: "Useful software from Example",
+  publisher: organization
+)
+
+@page_meta = PageStructuredData::Page.new(
+  title: "Example",
+  description: "Useful software from Example",
+  image: image_url("social/home.png"),
+  canonical_url: root_url,
+  page_types: [organization, website],
+  render_breadcrumb_json_ld: false
+)
+```
+
+### Forum Or Community Post
+
+Use `DiscussionForumPosting` for public, user-authored, timestamped posts:
+
+```ruby
+post_author = PageStructuredData::PageTypes::Person.new(
+  name: @post.user.name,
+  url: user_url(@post.user)
+)
+
+post_page_type = PageStructuredData::PageTypes::DiscussionForumPosting.new(
+  headline: @post.title,
+  text: @post.content_plaintext,
+  url: post_url(@post),
+  published_at: @post.created_at,
+  updated_at: @post.updated_at,
+  authors: [post_author],
+  comments_count: @post.comments_count
+)
+
+@page_meta = PageStructuredData::Page.new(
+  title: @post.title,
+  description: @post.excerpt,
+  canonical_url: post_url(@post),
+  page_type: post_page_type
+)
+```
+
+Only pass engagement counts that are public and visible on the rendered page.
+
+### Page-Local Site Name
+
+Override or suppress the global app name for one page:
+
+```ruby
+PageStructuredData.base_app_name = "Example"
+
+PageStructuredData::Page.new(
+  title: "Docs",
+  base_app_name: "Developer Docs"
+).page_title
+# => "Docs - Developer Docs"
+
+PageStructuredData::Page.new(
+  title: "Minimal",
+  base_app_name: ""
+).page_title
+# => "Minimal"
+```
+
+### Breadcrumb JSON-LD Control
+
+Control generated breadcrumb JSON-LD per page:
+
+```ruby
+PageStructuredData::Page.new(
+  title: "Landing Page",
+  render_breadcrumb_json_ld: false
+)
+```
+
+When the global default is disabled, a page can still opt in:
+
+```ruby
+PageStructuredData.render_default_breadcrumb_json_ld = false
+
+PageStructuredData::Page.new(
+  title: "Standalone Page",
+  render_breadcrumb_json_ld: true
+)
+```
+
+### Paginated Archive
+
+Use `robots` for archive, search, filtered, or paginated pages that should be crawlable but not indexed:
+
+```ruby
+@page_meta = PageStructuredData::Page.new(
+  title: "Articles",
+  extra_title: "Page #{@pagy.page}",
+  description: "Browse articles from Example",
+  canonical_url: articles_url(page: @pagy.page),
+  robots: "noindex,follow"
+)
+```
+
+`robots` can also be passed as an array:
+
+```ruby
+PageStructuredData::Page.new(
+  title: "Articles",
+  robots: ["noindex", "follow"]
+)
+```
+
 ## API Reference
 
 ### `PageStructuredData::Page`
@@ -281,18 +460,42 @@ PageStructuredData::Page.new(
   canonical_url: nil,
   fallback_image: nil,
   base_app_name: nil,
-  render_breadcrumb_json_ld: nil
+  render_breadcrumb_json_ld: nil,
+  robots: nil
 )
 ```
 
 `base_app_name` overrides `PageStructuredData.base_app_name` for one page. Pass an empty string to suppress the global app name for a specific page.
 `render_breadcrumb_json_ld` can be set to `true` or `false` for one page. Leave it as `nil` to use the global `PageStructuredData.render_default_breadcrumb_json_ld` behavior for generated default breadcrumbs. Explicit breadcrumb objects still render when the global default is disabled unless the page sets `render_breadcrumb_json_ld: false`.
+`robots` can be a string or array and renders a `<meta name="robots">` tag when present.
 
 Important methods:
 
 - `page_title`: returns the composed page title.
 - `json_lds`: returns the JSON-LD script tags for breadcrumbs and page type data.
 - `resolved_image`: returns `image` or `fallback_image`.
+- `robots_content`: returns the rendered robots directives.
+- `warnings`: returns soft validation warnings for the page and page types.
+- `valid?`: returns `true` when `warnings` is empty.
+
+### Soft Validation
+
+Page objects and page type objects expose non-blocking validation helpers:
+
+```ruby
+page_type = PageStructuredData::PageTypes::Organization.new(
+  name: nil,
+  url: nil
+)
+
+page_type.warnings
+# => ["name is required", "url is required"]
+
+page_type.valid?
+# => false
+```
+
+`warnings` does not stop rendering. It is intended for tests, previews, and development checks where you want to catch incomplete structured data before publishing a page.
 
 ### `PageStructuredData::Breadcrumbs`
 
@@ -320,9 +523,16 @@ PageStructuredData::PageTypes::BlogPosting.new(
   images: [],
   authors: [],
   image: nil,
+  description: nil,
   article_body: nil,
   text: nil,
   url: nil,
+  main_entity_of_page: nil,
+  publisher: nil,
+  article_section: nil,
+  keywords: nil,
+  word_count: nil,
+  in_language: nil,
   interaction_statistics: [],
   likes_count: nil,
   comments_count: nil,
@@ -338,9 +548,16 @@ PageStructuredData::PageTypes::NewsArticle.new(
   images: [],
   authors: [],
   image: nil,
+  description: nil,
   article_body: nil,
   text: nil,
   url: nil,
+  main_entity_of_page: nil,
+  publisher: nil,
+  article_section: nil,
+  keywords: nil,
+  word_count: nil,
+  in_language: nil,
   interaction_statistics: [],
   likes_count: nil,
   comments_count: nil,
@@ -351,6 +568,9 @@ PageStructuredData::PageTypes::NewsArticle.new(
 `authors` can be an array of hashes, `PageStructuredData::PageTypes::Person` objects, or other objects that respond to `to_h`.
 `image` is a convenience option for one image URL. Use `images` when passing multiple image URLs.
 `text` is an alias for `article_body`.
+`main_entity_of_page` can be a URL, hash, or object that responds to `to_h`.
+`publisher` can be a hash or another page type that responds to `to_h`, such as `PageStructuredData::PageTypes::Organization`.
+`keywords` can be a string or an array.
 `interaction_statistics` should be an array of `PageStructuredData::PageTypes::InteractionStatistic` objects or schema-compatible hashes.
 
 Important methods:
@@ -366,9 +586,16 @@ PageStructuredData::PageTypes::DiscussionForumPosting.new(
   images: [],
   authors: [],
   image: nil,
+  description: nil,
   article_body: nil,
   text: nil,
   url: nil,
+  main_entity_of_page: nil,
+  publisher: nil,
+  article_section: nil,
+  keywords: nil,
+  word_count: nil,
+  in_language: nil,
   interaction_statistics: [],
   likes_count: nil,
   comments_count: nil,

data/app/src/page_structured_data/page.rb

@@ -4,11 +4,11 @@ module PageStructuredData
   # Basic page metadata for any page
   class Page
     attr_reader :title, :description, :image, :extra_title, :breadcrumb, :page_type, :page_types, :canonical_url,
-                :fallback_image, :base_app_name, :render_breadcrumb_json_ld
+                :fallback_image, :base_app_name, :render_breadcrumb_json_ld, :robots
 
     def initialize(title:, description: nil, image: nil, # rubocop:disable Metrics/ParameterLists
                    extra_title: '', breadcrumb: nil, page_type: nil, page_types: nil, canonical_url: nil,
-                   fallback_image: nil, base_app_name: nil, render_breadcrumb_json_ld: nil)
+                   fallback_image: nil, base_app_name: nil, render_breadcrumb_json_ld: nil, robots: nil)
       @title = title
       @description = description
       @image = image
@@ -20,6 +20,7 @@ module PageStructuredData
       @fallback_image = fallback_image
       @base_app_name = base_app_name
       @render_breadcrumb_json_ld = render_breadcrumb_json_ld
+      @robots = robots
     end
 
     def title_with_hierarchies
@@ -47,12 +48,36 @@ module PageStructuredData
       image || fallback_image
     end
 
+    def robots_content
+      Array(robots).compact.join(',')
+    end
+
+    def warnings
+      page_warnings + page_type_warnings
+    end
+
+    def valid?
+      warnings.empty?
+    end
+
     private
 
     def resolved_page_types
       Array.wrap(page_types.presence || page_type).compact
     end
 
+    def page_warnings
+      title.present? ? [] : ['title is required']
+    end
+
+    def page_type_warnings
+      resolved_page_types.each_with_index.flat_map do |resolved_page_type, index|
+        next [] unless resolved_page_type.respond_to?(:warnings)
+
+        resolved_page_type.warnings.map { |warning| "page type #{index + 1}: #{warning}" }
+      end
+    end
+
     def breadcrumb_json_ld
       return if render_breadcrumb_json_ld == false
       return breadcrumb.json_ld(current_page_title: title) if breadcrumb.present?

data/app/src/page_structured_data/page_types/article.rb

@@ -6,18 +6,28 @@ module PageStructuredData
     class Article
       include SchemaNode
 
-      attr_reader :headline, :images, :published_at, :updated_at, :authors, :article_body, :url,
+      attr_reader :headline, :images, :published_at, :updated_at, :authors, :description, :article_body, :url,
+                  :main_entity_of_page, :publisher, :article_section, :keywords, :word_count, :in_language,
                   :interaction_statistics, :likes_count, :comments_count, :shares_count
 
       def initialize(headline:, published_at:, updated_at:, images: [], authors: [], image: nil, article_body: nil, text: nil,
-                     url: nil, interaction_statistics: [], likes_count: nil, comments_count: nil, shares_count: nil)
+                     description: nil, url: nil, main_entity_of_page: nil, publisher: nil, article_section: nil,
+                     keywords: nil, word_count: nil, in_language: nil, interaction_statistics: [], likes_count: nil,
+                     comments_count: nil, shares_count: nil)
         @headline = headline
         @images = image.present? ? Array(image) : Array(images)
         @published_at = published_at
         @updated_at = updated_at
         @authors = Array(authors)
+        @description = description
         @article_body = article_body || text
         @url = url
+        @main_entity_of_page = main_entity_of_page
+        @publisher = publisher
+        @article_section = article_section
+        @keywords = keywords
+        @word_count = word_count
+        @in_language = in_language
         @interaction_statistics = Array(interaction_statistics)
         @likes_count = likes_count
         @comments_count = comments_count
@@ -35,8 +45,15 @@ module PageStructuredData
           author: authors.map { |author| author_to_h(author) },
         }
 
+        node[:description] = description if description.present?
         node[:articleBody] = article_body if article_body.present?
         node[:url] = url if url.present?
+        node[:mainEntityOfPage] = object_to_h(main_entity_of_page) if main_entity_of_page.present?
+        node[:publisher] = object_to_h(publisher) if publisher.present?
+        node[:articleSection] = article_section if article_section.present?
+        node[:keywords] = keywords if keywords.present?
+        node[:wordCount] = word_count if word_count.present?
+        node[:inLanguage] = object_to_h(in_language) if in_language.present?
         node[:interactionStatistic] = interaction_statistics_to_h if interaction_statistics_to_h.any?
 
         node
@@ -50,6 +67,14 @@ module PageStructuredData
         )
       end
 
+      def warnings
+        required_attribute_warnings(
+          headline: headline,
+          published_at: published_at,
+          updated_at: updated_at
+        ) + author_warnings + publisher_warnings + interaction_statistic_warnings
+      end
+
       private
 
       def schema_type
@@ -68,6 +93,25 @@ module PageStructuredData
         )
       end
 
+      def author_warnings
+        authors.each_with_index.flat_map do |author, index|
+          if author.respond_to?(:warnings)
+            author.warnings.map { |warning| "author #{index + 1}: #{warning}" }
+          else
+            author_hash = object_to_h(author) || {}
+            required_attribute_warnings(name: author_hash[:name] || author_hash['name']).map do |warning|
+              "author #{index + 1}: #{warning}"
+            end
+          end
+        end
+      end
+
+      def publisher_warnings
+        return [] unless publisher.respond_to?(:warnings)
+
+        publisher.warnings.map { |warning| "publisher: #{warning}" }
+      end
+
       def interaction_statistics_to_h
         @interaction_statistics_to_h ||= all_interaction_statistics.map do |interaction_statistic|
           if interaction_statistic.respond_to?(:to_h)
@@ -95,6 +139,14 @@ module PageStructuredData
 
         InteractionStatistic.new(interaction_type: interaction_type, user_interaction_count: count)
       end
+
+      def interaction_statistic_warnings
+        all_interaction_statistics.each_with_index.flat_map do |interaction_statistic, index|
+          next [] unless interaction_statistic.respond_to?(:warnings)
+
+          interaction_statistic.warnings.map { |warning| "interaction statistic #{index + 1}: #{warning}" }
+        end
+      end
     end
   end
 end

data/app/src/page_structured_data/page_types/interaction_statistic.rb

@@ -44,6 +44,13 @@ module PageStructuredData
         )
       end
 
+      def warnings
+        required_attribute_warnings(
+          interaction_type: interaction_type,
+          user_interaction_count: user_interaction_count
+        )
+      end
+
       private
 
       def interaction_type_to_h

data/app/src/page_structured_data/page_types/organization.rb

@@ -40,8 +40,21 @@ module PageStructuredData
         )
       end
 
+      def warnings
+        required_attribute_warnings(name: name, url: url) + nested_warnings
+      end
+
       private
 
+      def nested_warnings
+        [founder, parent_organization].each_with_index.flat_map do |node, index|
+          next [] unless node.respond_to?(:warnings)
+
+          prefix = index.zero? ? 'founder' : 'parent organization'
+          node.warnings.map { |warning| "#{prefix}: #{warning}" }
+        end
+      end
+
       def parent_organization_to_h
         return object_to_h(parent_organization) if parent_organization.respond_to?(:to_h) && !parent_organization.is_a?(Hash)
         return unless parent_organization.present?

data/app/src/page_structured_data/page_types/person.rb

@@ -24,6 +24,10 @@ module PageStructuredData
           sameAs: same_as
         )
       end
+
+      def warnings
+        required_attribute_warnings(name: name)
+      end
     end
   end
 end

data/app/src/page_structured_data/page_types/schema_node.rb

@@ -4,6 +4,14 @@ module PageStructuredData
   module PageTypes
     # Shared helpers for schema.org hash values.
     module SchemaNode
+      def warnings
+        []
+      end
+
+      def valid?
+        warnings.empty?
+      end
+
       private
 
       def compact_node(node)
@@ -23,6 +31,12 @@ module PageStructuredData
       def blank_schema_value?(value)
         value.nil? || (value.respond_to?(:empty?) && value.empty?)
       end
+
+      def required_attribute_warnings(attributes)
+        attributes.each_with_object([]) do |(name, value), warnings|
+          warnings << "#{name} is required" if blank_schema_value?(value)
+        end
+      end
     end
   end
 end

data/app/src/page_structured_data/page_types/web_site.rb

@@ -36,6 +36,17 @@ module PageStructuredData
         )
       end
 
+      def warnings
+        required_attribute_warnings(name: name, url: url) + nested_warnings
+      end
+
+      private
+
+      def nested_warnings
+        return [] unless publisher.respond_to?(:warnings)
+
+        publisher.warnings.map { |warning| "publisher: #{warning}" }
+      end
     end
   end
 end

data/app/views/page_structured_data/_meta_tags.html.erb

@@ -4,11 +4,15 @@
 <% description = page&.description %>
 <% image = page&.resolved_image || default_image_url || nil %>
 <% canonical_url = page&.canonical_url %>
+<% robots_content = page&.robots_content %>
 
 <title><%= title %></title>
 <% if canonical_url.present? %>
 <link rel="canonical" href="<%= canonical_url %>">
 <% end %>
+<% if robots_content.present? %>
+<meta name="robots" content="<%= robots_content %>">
+<% end %>
 
 <meta name="title" content="<%= title %>">
 <% if description.present? %>

data/lib/page_structured_data/version.rb

@@ -1,3 +1,3 @@
 module PageStructuredData
-  VERSION = "1.0.13"
+  VERSION = "1.0.14"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: page_structured_data
 version: !ruby/object:Gem::Version
-  version: 1.0.13
+  version: 1.0.14
 platform: ruby
 authors:
 - Jey Geethan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-06 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -30,10 +30,11 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-description: PageStructuredData gives Rails applications a small page object and view
-  partial for rendering page titles, basic meta tags, Open Graph tags, Twitter card
-  tags, breadcrumb JSON-LD, article and forum post JSON-LD, Person, Organization,
-  and WebSite JSON-LD, and public interaction statistics.
+description: PageStructuredData keeps Rails SEO metadata, social sharing tags, and
+  schema.org JSON-LD in one page object and one view partial. It renders page titles,
+  basic meta tags, Open Graph tags, Twitter Card tags, breadcrumb JSON-LD, article
+  and forum post JSON-LD, Person, Organization, and WebSite JSON-LD, and public interaction
+  statistics.
 email:
 - opensource@rocketapex.com
 executables: []
@@ -91,5 +92,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: Render SEO, social, and JSON-LD metadata for Rails pages
+summary: One Rails page object for SEO, social, and JSON-LD metadata
 test_files: []