better_seo 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21564a3e273f4c6274fcafaddc9dc0b9e5e36524c1ca2a548ae48e455490034f
-  data.tar.gz: d82e2faf6d565f8be930ca24e9c3af7b60de23c8ed02dbcc0d14390c6725580b
+  metadata.gz: 4b1f457db06f6ed1a5654363c639448945eb0c8ee11f311203333edf3de5b499
+  data.tar.gz: bbb3f5e0f831a1f3437b1dd171b4e7c8cc953fc654b102670037da19cc96ae73
 SHA512:
-  metadata.gz: 656e243f281d61d4afac21dfdd2f18be27659ae695bc5d6770146fc7e234135a21e221847157d75bb50b1d41d2798094e87868fc8d91cac1eee0fe38e651c6eb
-  data.tar.gz: b65f741d51b2b192c2456356081ad908145d68f93d37e64c6ba5d45c3ae838820120d7c852592dd60d1f3da54e2bf21e88316bede5c2e9971d0af24d2cecbe50
+  metadata.gz: '0978f9a96df030f0b10c10e409c9938c7cca9d5b881212c10135de040f6e51cbd1631f5b6d76ffe9af9efad722336d4f522edb7abf6872d7abd86ae2e516f7ce'
+  data.tar.gz: e3fcdde3228d074d75f3a47abcfb81c5145c827191512642745254df0c93c8be1f7a2f82c0d9aaed783c64951dc1b753b436e928fd29d6fc22fce6091b97ea7b

data/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2025-01-23
+
+### Added
+- Structured Data (JSON-LD) support with comprehensive Schema.org implementation
+  - `StructuredData::Base` - Generic base class for all structured data types
+  - `StructuredData::Organization` - Company/organization information with full schema support
+  - `StructuredData::Article` - Blog posts, news articles with author/publisher metadata
+  - `StructuredData::Person` - Author profiles, team members with social links
+  - `StructuredData::Generator` - Helper class with factory methods
+- Structured data features
+  - Fluent API with method chaining for all types
+  - Automatic nested object handling (Person within Article, etc.)
+  - JSON-LD generation with `to_json` and `to_script_tag` methods
+  - Schema.org compliant output format
+  - Address handling with PostalAddress schema
+  - Social profile links with sameAs property
+- Rails integration patterns
+  - View helpers for structured data
+  - Layout integration examples
+  - Complete production examples
+- Comprehensive documentation
+  - 300+ lines of structured data documentation in README
+  - Complete examples for Organization, Article, Person
+  - Rails integration patterns and helper methods
+  - Nested data examples
+
+### Test Coverage
+- 491 tests passing (+107 from v0.5.0)
+- 99.64% code coverage (820/823 lines)
+- 117 new tests for structured data functionality
+
+## [0.5.0] - 2025-01-23
+
+### Added
+- Sitemap generation system with comprehensive XML sitemap support
+  - `Sitemap::UrlEntry` - Individual URL entry with full sitemap.org protocol support
+  - `Sitemap::Builder` - Fluent API for building sitemaps with method chaining
+  - `Sitemap::Generator` - High-level generator with multiple generation strategies
+- Sitemap generation methods
+  - `generate` - Generate from block with fluent builder
+  - `generate_from` - Generate from array of URLs
+  - `generate_from_collection` - Generate from model collections with lambda support
+  - `write_to_file` - Write sitemap directly to file with automatic directory creation
+- URL entry features
+  - Support for all sitemap attributes: loc, lastmod, changefreq, priority
+  - Automatic date formatting (Date, Time, DateTime objects)
+  - XML entity escaping for security
+  - Validation for URL format, protocol (HTTP/HTTPS), and required fields
+- Dynamic attribute generation
+  - Lambda/Proc support for dynamic lastmod, changefreq, and priority
+  - Conditional logic based on model attributes
+- Rails integration examples
+  - Controller actions for dynamic sitemap serving
+  - Rake tasks for sitemap generation
+  - Service object patterns for production use
+  - Multi-model sitemap examples
+- Comprehensive error handling
+  - 28 error class tests added
+  - Full coverage of all error types
+
+### Test Coverage
+- 384 tests passing (+98 from v0.4.0)
+- 99.71% code coverage (681/683 lines)
+- 69 new tests for sitemap functionality
+
 ## [0.4.0] - 2025-01-23
 
 ### Added

data/README.md

@@ -2,14 +2,14 @@
 
 A comprehensive SEO gem for Ruby and Rails applications. BetterSeo provides a clean, fluent DSL for managing meta tags, Open Graph, Twitter Cards, structured data, sitemaps, and more.
 
-[![Tests](https://img.shields.io/badge/tests-286%20passing-brightgreen)](https://github.com/yourusername/better_seo)
-[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/yourusername/better_seo)
+[![Tests](https://img.shields.io/badge/tests-491%20passing-brightgreen)](https://github.com/yourusername/better_seo)
+[![Coverage](https://img.shields.io/badge/coverage-99.64%25-brightgreen)](https://github.com/yourusername/better_seo)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-red)](https://www.ruby-lang.org)
 [![Rails](https://img.shields.io/badge/rails-%3E%3D%206.1-red)](https://rubyonrails.org)
 
 ## Features
 
-### ✅ Implemented (v0.2.0)
+### ✅ Implemented (v0.6.0)
 
 - **Core Configuration System**
   - Singleton configuration with block-style setup
@@ -38,23 +38,51 @@ A comprehensive SEO gem for Ruby and Rails applications. BetterSeo provides a cl
   - Automatic HTML safety with `raw` helper
   - Integration with global configuration defaults
 
+- **Sitemap Generation**
+  - **XML Sitemap Builder**: Fluent API for building sitemaps
+  - **Sitemap Generator**: Generate from blocks, arrays, or model collections
+  - **URL Entry**: Full sitemap.org protocol support (loc, lastmod, changefreq, priority)
+  - **Dynamic Generation**: Lambda support for dynamic attributes
+  - **File Writing**: Write sitemaps directly to files
+  - **Rails Integration**: Controller actions and Rake tasks
+  - **Validation**: Automatic URL validation (format, protocol)
+  - **Method Chaining**: Fluent interface for adding multiple URLs
+
+- **Structured Data (JSON-LD)**
+  - **Base Class**: Generic structured data with full Schema.org support
+  - **Organization**: Company/organization information with address, social profiles
+  - **Article**: Blog posts, news articles with author, publisher, metadata
+  - **Person**: Author profiles, team members with job title, social links
+  - **Generator Helper**: Factory methods and batch script tag generation
+  - **Nested Data**: Automatic handling of complex object relationships
+  - **JSON-LD Output**: Valid Schema.org JSON-LD format
+  - **Rails Integration**: View helpers and layout integration
+
 ### 🚧 Planned
 
-- **Advanced Generators** (v0.5.0)
-  - Schema.org JSON-LD generator
-  - Breadcrumbs generator
+- **Additional Structured Data Types** (v0.7.0)
+  - Product (e-commerce with price, availability)
+  - BreadcrumbList (navigation breadcrumbs)
+  - LocalBusiness (physical locations)
+  - Event (conferences, webinars)
+  - FAQPage, HowTo, Recipe
+
+- **Advanced Generators** (v0.7.0)
+  - Breadcrumbs HTML generator
   - AMP HTML generator
+  - Canonical URL management
 
-- **Advanced Rails Integration** (v0.5.0)
+- **Advanced Rails Integration** (v0.7.0)
   - Controller helpers for setting page SEO
   - Railtie for automatic initialization
   - Generator for initializer file
+  - Automatic meta tags from model attributes
 
-- **Sitemap Generation** (v0.5.0)
-  - XML sitemap builder
-  - Automatic Rails routes integration
-  - Multi-language sitemap support
-  - Sitemap index for large sites
+- **Advanced Sitemap Features** (v0.7.0)
+  - Multi-language sitemap support (hreflang)
+  - Sitemap index for large sites (50,000+ URLs)
+  - Image/video sitemap extensions
+  - News sitemap support
 
 - **Advanced Features** (v0.6.0+)
   - robots.txt generator
@@ -64,10 +92,12 @@ A comprehensive SEO gem for Ruby and Rails applications. BetterSeo provides a cl
 
 ## Installation
 
+### For Production Use (when published to RubyGems)
+
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'better_seo'
+gem 'better_seo', '~> 0.6.0'
 ```
 
 And then execute:
@@ -82,6 +112,23 @@ Or install it yourself as:
 gem install better_seo
 ```
 
+### For Development (from source)
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'better_seo', git: 'https://github.com/alessiobussolari/better_seo.git', tag: 'v0.6.0'
+```
+
+Or clone and build locally:
+
+```bash
+git clone https://github.com/alessiobussolari/better_seo.git
+cd better_seo
+gem build better_seo.gemspec
+gem install better_seo-0.6.0.gem
+```
+
 ## Quick Start
 
 ### 1. Configuration
@@ -555,6 +602,740 @@ Then use it in your views:
     og_image: url_for(@article.cover_image) %>
 ```
 
+### 6. Sitemap Generation
+
+BetterSeo provides a comprehensive sitemap generation system with support for XML sitemaps, dynamic content, and model collections.
+
+#### Basic Sitemap Generation
+
+Generate a simple sitemap using the block syntax:
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  sitemap.add_url("https://example.com")
+  sitemap.add_url("https://example.com/about")
+  sitemap.add_url("https://example.com/contact")
+end
+
+puts xml
+# <?xml version="1.0" encoding="UTF-8"?>
+# <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+#   <url>
+#     <loc>https://example.com</loc>
+#     <changefreq>weekly</changefreq>
+#     <priority>0.5</priority>
+#   </url>
+#   ...
+# </urlset>
+```
+
+#### URL Entry with Full Attributes
+
+Add URLs with all sitemap attributes (lastmod, changefreq, priority):
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  sitemap.add_url(
+    "https://example.com",
+    lastmod: Date.today,
+    changefreq: "daily",
+    priority: 1.0
+  )
+
+  sitemap.add_url(
+    "https://example.com/blog",
+    lastmod: "2024-01-15",
+    changefreq: "weekly",
+    priority: 0.8
+  )
+
+  sitemap.add_url(
+    "https://example.com/about",
+    changefreq: "monthly",
+    priority: 0.5
+  )
+end
+```
+
+**Valid changefreq values**: `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`
+
+**Priority range**: 0.0 to 1.0 (default: 0.5)
+
+#### Method Chaining
+
+The builder supports fluent method chaining:
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  sitemap
+    .add_url("https://example.com", priority: 1.0)
+    .add_url("https://example.com/about", priority: 0.8)
+    .add_url("https://example.com/contact", priority: 0.6)
+end
+```
+
+#### Generate from Array
+
+Create a sitemap from an array of URLs:
+
+```ruby
+urls = [
+  "https://example.com",
+  "https://example.com/about",
+  "https://example.com/contact",
+  "https://example.com/blog"
+]
+
+xml = BetterSeo::Sitemap::Generator.generate_from(
+  urls,
+  changefreq: "weekly",
+  priority: 0.7
+)
+```
+
+#### Generate from Model Collection
+
+Generate sitemaps dynamically from your Rails models:
+
+```ruby
+# Simple example with Post model
+xml = BetterSeo::Sitemap::Generator.generate_from_collection(
+  Post.published,
+  url: ->(post) { "https://example.com/posts/#{post.slug}" },
+  lastmod: ->(post) { post.updated_at },
+  changefreq: "weekly",
+  priority: 0.8
+)
+```
+
+**Dynamic attributes with lambdas**:
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate_from_collection(
+  Article.all,
+  url: ->(article) { "https://example.com/articles/#{article.slug}" },
+  lastmod: ->(article) { article.updated_at },
+  changefreq: ->(article) do
+    article.featured? ? "daily" : "weekly"
+  end,
+  priority: ->(article) do
+    article.featured? ? 0.9 : 0.6
+  end
+)
+```
+
+#### Rails Routes Integration
+
+Generate sitemap from Rails routes:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Your routes...
+
+  # Sitemap endpoint
+  get '/sitemap.xml', to: 'sitemaps#index', defaults: { format: 'xml' }
+end
+
+# app/controllers/sitemaps_controller.rb
+class SitemapsController < ApplicationController
+  def index
+    @sitemap_xml = generate_sitemap
+    render xml: @sitemap_xml
+  end
+
+  private
+
+  def generate_sitemap
+    BetterSeo::Sitemap::Generator.generate do |sitemap|
+      # Static pages
+      sitemap.add_url(root_url, priority: 1.0, changefreq: "daily")
+      sitemap.add_url(about_url, priority: 0.8, changefreq: "monthly")
+      sitemap.add_url(contact_url, priority: 0.7, changefreq: "monthly")
+
+      # Dynamic content from models
+      Post.published.find_each do |post|
+        sitemap.add_url(
+          post_url(post),
+          lastmod: post.updated_at,
+          changefreq: "weekly",
+          priority: 0.8
+        )
+      end
+
+      Category.all.find_each do |category|
+        sitemap.add_url(
+          category_url(category),
+          lastmod: category.updated_at,
+          changefreq: "weekly",
+          priority: 0.7
+        )
+      end
+    end
+  end
+end
+```
+
+#### Write Sitemap to File
+
+Save sitemap directly to a file:
+
+```ruby
+# In a Rake task or script
+BetterSeo::Sitemap::Generator.write_to_file('public/sitemap.xml') do |sitemap|
+  sitemap.add_url("https://example.com", priority: 1.0)
+
+  Post.published.find_each do |post|
+    sitemap.add_url(
+      "https://example.com/posts/#{post.slug}",
+      lastmod: post.updated_at,
+      changefreq: "weekly",
+      priority: 0.8
+    )
+  end
+end
+
+# Returns the file path: "public/sitemap.xml"
+```
+
+#### Rake Task for Sitemap Generation
+
+Create a Rake task to regenerate your sitemap:
+
+```ruby
+# lib/tasks/sitemap.rake
+namespace :sitemap do
+  desc "Generate sitemap.xml"
+  task generate: :environment do
+    file_path = BetterSeo::Sitemap::Generator.write_to_file('public/sitemap.xml') do |sitemap|
+      # Add static pages
+      sitemap.add_url("#{ENV['SITE_URL']}", priority: 1.0, changefreq: "daily")
+      sitemap.add_url("#{ENV['SITE_URL']}/about", priority: 0.8)
+      sitemap.add_url("#{ENV['SITE_URL']}/contact", priority: 0.7)
+
+      # Add dynamic content
+      Post.published.find_each do |post|
+        sitemap.add_url(
+          "#{ENV['SITE_URL']}/posts/#{post.slug}",
+          lastmod: post.updated_at,
+          changefreq: "weekly",
+          priority: 0.8
+        )
+      end
+    end
+
+    puts "Sitemap generated at #{file_path}"
+  end
+end
+
+# Run with: rake sitemap:generate
+```
+
+#### Using the Builder Directly
+
+For more control, use the Builder class directly:
+
+```ruby
+builder = BetterSeo::Sitemap::Builder.new
+
+# Add URLs
+builder.add_url("https://example.com", priority: 1.0)
+builder.add_url("https://example.com/about", priority: 0.8)
+
+# Add multiple URLs at once
+builder.add_urls(
+  ["https://example.com/blog", "https://example.com/contact"],
+  changefreq: "weekly",
+  priority: 0.7
+)
+
+# Remove a URL
+builder.remove_url("https://example.com/contact")
+
+# Check size
+puts builder.size # => 3
+
+# Iterate over URLs
+builder.each do |url|
+  puts "#{url.loc} - Priority: #{url.priority}"
+end
+
+# Generate XML
+xml = builder.to_xml
+
+# Validate all URLs
+builder.validate! # Raises ValidationError if any URL is invalid
+
+# Clear all URLs
+builder.clear
+```
+
+#### URL Entry Details
+
+Work with individual URL entries:
+
+```ruby
+entry = BetterSeo::Sitemap::UrlEntry.new(
+  "https://example.com/page",
+  lastmod: Date.today,
+  changefreq: "daily",
+  priority: 0.8
+)
+
+# Access attributes
+entry.loc         # => "https://example.com/page"
+entry.lastmod     # => "2024-01-15"
+entry.changefreq  # => "daily"
+entry.priority    # => 0.8
+
+# Update attributes
+entry.lastmod = Date.new(2024, 1, 20)
+entry.changefreq = "weekly"
+entry.priority = 0.9
+
+# Generate XML for single entry
+entry.to_xml
+# <url>
+#   <loc>https://example.com/page</loc>
+#   <lastmod>2024-01-20</lastmod>
+#   <changefreq>weekly</changefreq>
+#   <priority>0.9</priority>
+# </url>
+
+# Convert to hash
+entry.to_h
+# {
+#   loc: "https://example.com/page",
+#   lastmod: "2024-01-20",
+#   changefreq: "weekly",
+#   priority: 0.9
+# }
+
+# Validate
+entry.validate! # Raises ValidationError if invalid
+```
+
+#### Advanced: Multi-Model Sitemap
+
+Combine multiple models in a single sitemap:
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  # Homepage
+  sitemap.add_url("https://example.com", priority: 1.0, changefreq: "daily")
+
+  # Blog posts
+  Post.published.find_each do |post|
+    sitemap.add_url(
+      "https://example.com/posts/#{post.slug}",
+      lastmod: post.updated_at,
+      changefreq: post.featured? ? "daily" : "weekly",
+      priority: post.featured? ? 0.9 : 0.7
+    )
+  end
+
+  # Categories
+  Category.all.find_each do |category|
+    sitemap.add_url(
+      "https://example.com/categories/#{category.slug}",
+      lastmod: category.updated_at,
+      changefreq: "weekly",
+      priority: 0.6
+    )
+  end
+
+  # Static pages
+  %w[about contact privacy terms].each do |page|
+    sitemap.add_url(
+      "https://example.com/#{page}",
+      changefreq: "monthly",
+      priority: 0.5
+    )
+  end
+end
+```
+
+#### Validation
+
+All URLs are automatically validated when generating:
+
+```ruby
+# This will raise BetterSeo::ValidationError
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  sitemap.add_url("")  # Error: Location is required
+  sitemap.add_url("not-a-valid-url")  # Error: Invalid URL format
+  sitemap.add_url("ftp://example.com")  # Error: Must be HTTP/HTTPS
+end
+
+# Validate manually
+builder = BetterSeo::Sitemap::Builder.new
+builder.add_url("https://example.com")
+builder.validate!  # Returns true if all URLs valid
+```
+
+#### Complete Example: Production Sitemap
+
+```ruby
+# app/services/sitemap_generator_service.rb
+class SitemapGeneratorService
+  def self.generate
+    BetterSeo::Sitemap::Generator.write_to_file(Rails.root.join('public', 'sitemap.xml')) do |sitemap|
+      add_static_pages(sitemap)
+      add_blog_posts(sitemap)
+      add_categories(sitemap)
+      add_products(sitemap) if defined?(Product)
+    end
+  end
+
+  private_class_method def self.add_static_pages(sitemap)
+    sitemap.add_url(Rails.application.routes.url_helpers.root_url, priority: 1.0, changefreq: "daily")
+    sitemap.add_url(Rails.application.routes.url_helpers.about_url, priority: 0.8, changefreq: "monthly")
+    sitemap.add_url(Rails.application.routes.url_helpers.contact_url, priority: 0.7, changefreq: "monthly")
+  end
+
+  private_class_method def self.add_blog_posts(sitemap)
+    Post.published.find_each do |post|
+      sitemap.add_url(
+        Rails.application.routes.url_helpers.post_url(post),
+        lastmod: post.updated_at,
+        changefreq: post.frequently_updated? ? "daily" : "weekly",
+        priority: calculate_post_priority(post)
+      )
+    end
+  end
+
+  private_class_method def self.add_categories(sitemap)
+    Category.all.find_each do |category|
+      sitemap.add_url(
+        Rails.application.routes.url_helpers.category_url(category),
+        lastmod: category.posts.maximum(:updated_at),
+        changefreq: "weekly",
+        priority: 0.6
+      )
+    end
+  end
+
+  private_class_method def self.add_products(sitemap)
+    Product.available.find_each do |product|
+      sitemap.add_url(
+        Rails.application.routes.url_helpers.product_url(product),
+        lastmod: product.updated_at,
+        changefreq: "daily",
+        priority: product.featured? ? 0.95 : 0.75
+      )
+    end
+  end
+
+  private_class_method def self.calculate_post_priority(post)
+    base_priority = 0.7
+    base_priority += 0.2 if post.featured?
+    base_priority += 0.1 if post.comments_count > 10
+    [base_priority, 1.0].min
+  end
+end
+
+# Call from rake task or controller:
+# SitemapGeneratorService.generate
+```
+
+### 7. Structured Data (JSON-LD)
+
+BetterSeo provides comprehensive support for Schema.org structured data using JSON-LD format, helping search engines better understand your content.
+
+#### Basic Usage
+
+Create structured data objects and generate JSON-LD script tags:
+
+```ruby
+# Create an Organization
+org = BetterSeo::StructuredData::Organization.new
+org.name("Acme Corporation")
+org.url("https://www.acme.com")
+org.logo("https://www.acme.com/logo.png")
+org.description("Leading provider of innovative solutions")
+
+# Generate JSON-LD script tag
+org.to_script_tag
+# <script type="application/ld+json">
+# {
+#   "@context": "https://schema.org",
+#   "@type": "Organization",
+#   "name": "Acme Corporation",
+#   ...
+# }
+# </script>
+```
+
+#### Available Types
+
+**Organization** - Company/organization information:
+
+```ruby
+org = BetterSeo::StructuredData::Organization.new
+org.name("Tech Innovations Inc")
+org.url("https://techinnovations.com")
+org.logo("https://techinnovations.com/logo.png")
+org.description("Innovative technology solutions")
+org.email("contact@techinnovations.com")
+org.telephone("+1-555-0100")
+org.address(
+  street: "123 Tech Boulevard",
+  city: "San Francisco",
+  region: "CA",
+  postal_code: "94105",
+  country: "US"
+)
+org.same_as([
+  "https://twitter.com/techinnovations",
+  "https://linkedin.com/company/techinnovations"
+])
+org.founding_date("2015-03-20")
+```
+
+**Article** - Blog posts, news articles, content:
+
+```ruby
+article = BetterSeo::StructuredData::Article.new
+article.headline("The Future of Web Development")
+article.description("An in-depth analysis of emerging trends")
+article.image("https://example.com/article-image.jpg")
+article.author("Jane Smith")  # Or use Person object
+article.date_published("2024-01-15T09:00:00Z")
+article.date_modified("2024-01-20T14:30:00Z")
+article.url("https://example.com/articles/future-of-web-dev")
+article.word_count(2500)
+article.keywords(["Web Development", "Technology", "Trends"])
+article.article_section("Technology")
+```
+
+**Person** - Author profiles, team members:
+
+```ruby
+person = BetterSeo::StructuredData::Person.new
+person.name("Dr. Jane Smith")
+person.given_name("Jane")
+person.family_name("Smith")
+person.email("jane@example.com")
+person.url("https://janesmith.dev")
+person.image("https://janesmith.dev/profile.jpg")
+person.job_title("Chief Technology Officer")
+person.telephone("+1-555-0199")
+person.same_as([
+  "https://twitter.com/janesmith",
+  "https://linkedin.com/in/janesmith"
+])
+```
+
+#### Method Chaining
+
+All structured data classes support fluent method chaining:
+
+```ruby
+org = BetterSeo::StructuredData::Organization.new
+  .name("Acme Corp")
+  .url("https://acme.com")
+  .logo("https://acme.com/logo.png")
+  .description("Innovation at its finest")
+```
+
+#### Nested Structured Data
+
+Combine multiple structured data objects:
+
+```ruby
+# Create publisher organization
+publisher = BetterSeo::StructuredData::Organization.new
+publisher.name("Tech Publishing Co")
+publisher.logo("https://techpub.com/logo.png")
+
+# Create author person
+author = BetterSeo::StructuredData::Person.new
+author.name("Jane Smith")
+author.email("jane@techpub.com")
+author.url("https://janesmith.dev")
+
+# Create article with nested data
+article = BetterSeo::StructuredData::Article.new
+article.headline("Introduction to Ruby on Rails")
+article.description("A comprehensive guide for beginners")
+article.image("https://example.com/rails-guide.jpg")
+article.author(author)  # Nested Person
+article.publisher(publisher)  # Nested Organization
+article.date_published("2024-01-15")
+
+# Generates nested JSON-LD automatically
+article.to_script_tag
+```
+
+#### Using the Generator Helper
+
+The Generator class provides convenient factory methods:
+
+```ruby
+# Create with block
+org = BetterSeo::StructuredData::Generator.organization do |o|
+  o.name("Acme Corp")
+  o.url("https://acme.com")
+  o.logo("https://acme.com/logo.png")
+end
+
+article = BetterSeo::StructuredData::Generator.article do |a|
+  a.headline("Amazing Article")
+  a.author("John Doe")
+  a.date_published("2024-01-15")
+end
+
+person = BetterSeo::StructuredData::Generator.person do |p|
+  p.name("John Doe")
+  p.email("john@example.com")
+end
+
+# Generate multiple script tags at once
+tags = BetterSeo::StructuredData::Generator.generate_script_tags([org, article, person])
+# Returns all three script tags joined with newlines
+```
+
+#### Rails Integration
+
+Add structured data to your Rails views:
+
+```erb
+<%# app/views/articles/show.html.erb %>
+<%
+  author = BetterSeo::StructuredData::Generator.person do |p|
+    p.name(@article.author.name)
+    p.email(@article.author.email)
+    p.url(@article.author.website)
+  end
+
+  article_sd = BetterSeo::StructuredData::Generator.article do |a|
+    a.headline(@article.title)
+    a.description(@article.excerpt)
+    a.image(url_for(@article.cover_image))
+    a.author(author)
+    a.date_published(@article.published_at.iso8601)
+    a.date_modified(@article.updated_at.iso8601)
+    a.url(article_url(@article))
+    a.word_count(@article.word_count)
+    a.keywords(@article.tags.pluck(:name))
+  end
+%>
+
+<%== article_sd.to_script_tag %>
+```
+
+Or in a helper:
+
+```ruby
+# app/helpers/structured_data_helper.rb
+module StructuredDataHelper
+  def article_structured_data(article)
+    author = BetterSeo::StructuredData::Generator.person do |p|
+      p.name(article.author.name)
+      p.url(author_url(article.author))
+    end
+
+    article_sd = BetterSeo::StructuredData::Generator.article do |a|
+      a.headline(article.title)
+      a.description(article.excerpt)
+      a.author(author)
+      a.date_published(article.published_at.iso8601)
+      a.url(article_url(article))
+    end
+
+    article_sd.to_script_tag.html_safe
+  end
+
+  def organization_structured_data
+    org = BetterSeo::StructuredData::Generator.organization do |o|
+      o.name(Rails.application.config.site_name)
+      o.url(root_url)
+      o.logo(image_url('logo.png'))
+      o.same_as([
+        "https://twitter.com/yourcompany",
+        "https://facebook.com/yourcompany"
+      ])
+    end
+
+    org.to_script_tag.html_safe
+  end
+end
+```
+
+Then in your layout:
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<head>
+  ...
+  <%= organization_structured_data %>
+</head>
+```
+
+And in article views:
+
+```erb
+<%# app/views/articles/show.html.erb %>
+<%= article_structured_data(@article) %>
+```
+
+#### Complete Example
+
+```ruby
+# Create complete structured data for a blog article
+publisher = BetterSeo::StructuredData::Generator.organization do |o|
+  o.name("Tech Blog Publishing")
+  o.url("https://techblog.com")
+  o.logo("https://techblog.com/logo.png")
+end
+
+author = BetterSeo::StructuredData::Generator.person do |p|
+  p.name("Dr. Sarah Johnson")
+  p.email("sarah@techblog.com")
+  p.url("https://sarahjohnson.dev")
+  p.job_title("Senior Technology Writer")
+end
+
+article = BetterSeo::StructuredData::Generator.article do |a|
+  a.headline("The Complete Guide to Ruby on Rails in 2024")
+  a.description("Everything you need to know about Rails")
+  a.image([
+    "https://techblog.com/images/rails-2024-1.jpg",
+    "https://techblog.com/images/rails-2024-2.jpg"
+  ])
+  a.author(author)
+  a.publisher(publisher)
+  a.date_published("2024-01-15T09:00:00Z")
+  a.date_modified("2024-01-20T15:30:00Z")
+  a.url("https://techblog.com/rails-complete-guide-2024")
+  a.word_count(3500)
+  a.keywords(["Ruby on Rails", "Web Development", "2024"])
+  a.article_section("Programming")
+end
+
+# Get JSON-LD
+json_ld = article.to_json
+
+# Get script tag for HTML
+script_tag = article.to_script_tag
+
+# Or generate all at once
+all_tags = BetterSeo::StructuredData::Generator.generate_script_tags([
+  publisher,
+  author,
+  article
+])
+```
+
+#### Benefits
+
+- **SEO Enhancement**: Help search engines understand your content better
+- **Rich Snippets**: Enable rich results in search results (ratings, images, etc.)
+- **Type Safety**: Fluent API with method chaining
+- **Nested Data**: Automatic handling of complex relationships
+- **Standards Compliant**: Follows Schema.org specifications
+- **Easy Integration**: Works seamlessly with Rails views and helpers
+
 ## Configuration Reference
 
 ### Global Configuration

data/lib/better_seo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BetterSeo
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/better_seo.rb

@@ -14,6 +14,14 @@ require_relative "better_seo/generators/meta_tags_generator"
 require_relative "better_seo/generators/open_graph_generator"
 require_relative "better_seo/generators/twitter_cards_generator"
 require_relative "better_seo/rails/helpers/seo_helper"
+require_relative "better_seo/sitemap/url_entry"
+require_relative "better_seo/sitemap/builder"
+require_relative "better_seo/sitemap/generator"
+require_relative "better_seo/structured_data/base"
+require_relative "better_seo/structured_data/organization"
+require_relative "better_seo/structured_data/article"
+require_relative "better_seo/structured_data/person"
+require_relative "better_seo/structured_data/generator"
 
 module BetterSeo
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: better_seo
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-22 00:00:00.000000000 Z
+date: 2025-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -53,8 +53,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.22'
 description: BetterSeo provides a clean, fluent DSL for managing meta tags, Open Graph,
-  Twitter Cards, and more. Features include automatic HTML generation, validation,
-  Rails view helpers, and 100% test coverage.
+  Twitter Cards, XML sitemaps, and more. Features include automatic HTML generation,
+  dynamic sitemap generation, validation, Rails integration, and 99.7% test coverage.
 email:
 - alessio@cosmic.tech
 executables: []