page_structured_data 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb34fae60cc0d7ec3b9d686d8a5977d515fd29784d6beee5b7b63af55a902555
-  data.tar.gz: 8e81d0952b1e139cbd1f74d3a6f6518225e7d9c5da6be62e8c87e7f8a1c57094
+  metadata.gz: 8e6e417c38d0a25d8e3270315eb9d98434eb9dbc93e7860667a96e457b94bfa9
+  data.tar.gz: e3f2b717b5b01cd49c90675fb1a74199b89492c298fa93474ad75772530edf32
 SHA512:
-  metadata.gz: 8bddeabf6322a0942c71a0dde014be7a1030d43d16d53fed97fd8fad206681ae3060ed06a7a19885bdcace26a215813e0d190fb5e72edd7ab9d0127fa90b683c
-  data.tar.gz: d55d272089d34357730ae7c079bb428b53de64c0c7aa9b7745589ca7156b07d4e3d1ef7d96921f44be075d1b7ae2337fc0ae56f95f498ebd6ef13eec6502e740
+  metadata.gz: 80bc6fed7640148b6f7e23c9ce3aec0bdb719ce8d4e7136a63dba0b0b2d7bc277de96b500e10cca9f5058b0a8fee0b8f81ce6cfc894db984472c99e65401af29
+  data.tar.gz: 9aefe55598d3e63ab69df53c2fbc95ea6697b46b7d1ce5b19909e8a54b6bb346bc460c858d572bfd2c07cc49c05fe12d6a9e1fb2be026ce58efc01aa0b80f879

data/README.md

@@ -1,103 +1,251 @@
 # PageStructuredData
-Use this gem to churn out meta tags for your rails webpages. This also renders meta tags for the following:
-1. Page `<title>` tag with proper hyphenation when used with breadcrumbs
-2. Basic `<meta>` tags
-2. Twitter meta tags
-3. Open graph meta tags
-4. Google Schema JSON-LD `<script>` tags
+
+PageStructuredData is a small Rails engine for rendering page-level SEO and social sharing metadata from one page object.
+
+It helps Rails applications render:
+
+- A `<title>` tag
+- Basic `title`, `description`, and `image` meta tags
+- Open Graph tags
+- Twitter card tags
+- Google-compatible JSON-LD structured data
+- Breadcrumb structured data
+- Article structured data for `BlogPosting` and `NewsArticle`
+
+## Requirements
+
+- Rails 7.0 or newer
+- Slim 4.1 or newer
+- A Ruby version supported by your Rails version
 
 ## Installation
-Add this line to your application's Gemfile:
+
+Add the gem to your application's Gemfile:
 
 ```ruby
 gem "page_structured_data"
 ```
 
-And then execute:
+Then install it:
+
 ```bash
-$ bundle
+bundle install
 ```
 
-Or install it yourself as:
-```bash
-$ gem install page_structured_data
+## Configuration
+
+Configure application-wide defaults in an initializer:
+
+```ruby
+# config/initializers/page_structured_data.rb
+Rails.application.config.after_initialize do
+  PageStructuredData.config do |config|
+    config.base_app_name = "AwesomestApp"
+  end
+end
 ```
 
-## Usage
+`base_app_name` is appended to generated page titles.
 
-### Layouts
+For example:
 
-Add the following in your layout to include the basic meta tags by default
+```ruby
+PageStructuredData.base_app_name = "AwesomestApp"
 
-```erbruby
-<%= render 'page_structured_data/meta_tags', page: @page_meta, 
-    default_image_url: image_url('<path_to_default_image>') %>
+page = PageStructuredData::Page.new(
+  title: "Pricing",
+  extra_title: "Plans",
+  description: "Simple pricing for AwesomestApp"
+)
+
+page.page_title
+# => "Pricing - Plans - AwesomestApp"
+```
+
+## Rendering Meta Tags
+
+Render the bundled partial from your application layout:
+
+```erb
+<%= render "page_structured_data/meta_tags",
+           page: @page_meta,
+           default_image_url: image_url("social/default.png") %>
 ```
 
-Note: This doesn't include csrf or any other security or viewport related meta tags.
+`default_image_url` is optional. It is used when the page object does not provide an image.
+
+This partial is only responsible for SEO, social sharing, and structured-data tags. Keep your normal Rails layout tags, such as CSRF, CSP, viewport, and favicon tags, in your application layout.
 
-### Views
+## Basic Page Metadata
 
-In your views, please define the `@page_meta` as follows
+Set `@page_meta` in the controller or view before the layout renders:
 
 ```ruby
-<% @page_meta = PageStructuredData::Page.new(title: 'Home', extra_title: "Official Page",
-        description: 'Welcome to my Page') %>
+@page_meta = PageStructuredData::Page.new(
+  title: "Home",
+  extra_title: "Official Page",
+  description: "Welcome to my page",
+  image: image_url("social/home.png")
+)
 ```
 
-The instance variable will be used in the layout to create proper meta tags. Most attributes are self explanatory. `extra_title` is used to append to the title. 
+The generated title is built from:
 
-### Config
+1. `title`
+2. `extra_title`, when present
+3. breadcrumb titles, when present
+4. `PageStructuredData.base_app_name`, when present
 
-Configure the application wide settings as follows:
+The parts are joined with `" - "`.
 
-```erbruby
-# config/initializers/page_structured_data.rb
-Rails.application.config.after_initialize do
-  PageStructuredData.config do |config|
-    config.base_app_name = 'AwesomestApp' # or use any application constant as this is called after_initialize
-  end
-end
+## Breadcrumbs
+
+Create breadcrumbs with a hierarchy of page titles and URLs:
+
+```ruby
+breadcrumbs = PageStructuredData::Breadcrumbs.new(
+  hierarchy: [
+    { title: "Resources", href: resources_url },
+    { title: "Articles", href: resources_articles_url }
+  ]
+)
+```
+
+Pass the breadcrumbs into the page object:
+
+```ruby
+@page_meta = PageStructuredData::Page.new(
+  title: "How to Structure Metadata",
+  description: "A guide to page metadata and structured data",
+  breadcrumb: breadcrumbs
+)
 ```
 
-### Breadcrumbs
+This renders `BreadcrumbList` JSON-LD similar to Google's breadcrumb structured data format.
+
+Current compatibility note: when no breadcrumb object is passed, `PageStructuredData::Page` still creates an empty breadcrumb trail for the current page. This is existing behavior and should be considered part of the current public API.
+
+## Article Page Types
+
+PageStructuredData includes page types for:
 
-Create a list of breadcrumbs like this:
+- [`BlogPosting`](https://schema.org/BlogPosting)
+- [`NewsArticle`](https://schema.org/NewsArticle)
 
-```erbruby
-<% breadcrumb = PageStructuredData::Breadcrumbs.new(hierarchy: [{ title: 'Resources', href: resources_url }, { title: 'Articles', href: resources_articles_url }]) %>
+Use a page type when the current page represents an article:
+
+```ruby
+article_page_type = PageStructuredData::PageTypes::BlogPosting.new(
+  headline: @article.title,
+  published_at: @article.published_at,
+  updated_at: @article.updated_at,
+  authors: [
+    {
+      name: @article.authors.first.name,
+      url: @article.authors.first.website
+    }
+  ],
+  images: [
+    main_app.url_for(@article.cover_image.variant(:standard))
+  ]
+)
+
+@page_meta = PageStructuredData::Page.new(
+  title: @article.title,
+  description: @article.summary,
+  image: main_app.url_for(@article.cover_image.variant(:standard)),
+  breadcrumb: breadcrumbs,
+  page_type: article_page_type
+)
 ```
 
-And include it in the `Page.new` as:
+For news pages, use `PageStructuredData::PageTypes::NewsArticle` with the same arguments.
+
+## API Reference
+
+### `PageStructuredData::Page`
 
-```erbruby
-<% @page_meta = PageStructuredData::Page.new(title: 'Home', extra_title: "Official Page",
-        description: 'Welcome to my Page', breadcrumb: breadcrumb) %>
+```ruby
+PageStructuredData::Page.new(
+  title:,
+  description: nil,
+  image: nil,
+  extra_title: "",
+  breadcrumb: nil,
+  page_type: nil
+)
 ```
 
-This will create a JSON+LD breadcrumbs similar to [Breadcrumbs](https://developers.google.com/search/docs/appearance/structured-data/breadcrumb)
+Important methods:
+
+- `page_title`: returns the composed page title.
+- `json_lds`: returns the JSON-LD script tags for breadcrumbs and page type data.
 
-### PageTypes
+### `PageStructuredData::Breadcrumbs`
+
+```ruby
+PageStructuredData::Breadcrumbs.new(
+  hierarchy: [
+    { title: "Resources", href: "https://example.com/resources" }
+  ]
+)
+```
 
-Currently this gem supports the following page types:
+Important methods:
 
-* [BlogPosting](https://schema.org/BlogPosting)
-* [NewsArticle](https://schema.org/NewsArticle)
+- `titles`: returns breadcrumb titles.
+- `json_ld(current_page_title:)`: returns a `BreadcrumbList` JSON-LD script tag.
 
-To use these, it is similar to breadcrumbs: include them in `Page.new` and it the json+ld will be automatically included.
+### Article Page Types
 
-```erbruby
-<% article_page_type = PageStructuredData::PageTypes::BlogPosting.new(headline: @article.title, published_at: @article.published_at,
-        updated_at: @article.updated_at, authors: [name: @article.authors.first.name, url: @article.authors.first.website],
-        images: [main_app.url_for(@article.cover_image.variant(:standard))]) %>
-<% @page_meta = PageStructuredData::Page.new(title: 'Home', extra_title: "Official Page",
-                                             description: 'Welcome to my Page', page_type: article_page_type) %>
+```ruby
+PageStructuredData::PageTypes::BlogPosting.new(
+  headline:,
+  published_at:,
+  updated_at:,
+  images: [],
+  authors: []
+)
 ```
 
-Just replace BlogPosting class with the other type for other page types.
+```ruby
+PageStructuredData::PageTypes::NewsArticle.new(
+  headline:,
+  published_at:,
+  updated_at:,
+  images: [],
+  authors: []
+)
+```
+
+`authors` should be an array of hashes with `:name` and `:url` keys.
+
+## Development
+
+Run the test suite:
+
+```bash
+bundle exec rake test
+```
+
+Verify the gem can be required:
+
+```bash
+ruby -Ilib -e 'require "page_structured_data"; puts PageStructuredData::VERSION'
+```
+
+## Compatibility Policy
+
+This gem is used in production applications. Changes should preserve existing public APIs and rendered output unless a breaking change is intentionally released in a major version.
+
+Prefer additive APIs and tests that document current behavior before refactoring internals.
 
 ## Contributing
-Please raise a PR to be validated and merged.
+
+Bug reports and pull requests are welcome on GitHub.
+
+When contributing, please include tests for user-visible behavior and keep changes focused. For compatibility-sensitive behavior, describe the expected impact in the pull request.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/page_structured_data/engine.rb

@@ -1,3 +1,6 @@
+require "rails"
+require "action_dispatch/railtie"
+
 module PageStructuredData
   class Engine < ::Rails::Engine
     isolate_namespace PageStructuredData

data/lib/page_structured_data/version.rb

@@ -1,3 +1,3 @@
 module PageStructuredData
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: page_structured_data
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Jey Geethan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-30 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails