better_seo 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21564a3e273f4c6274fcafaddc9dc0b9e5e36524c1ca2a548ae48e455490034f
-  data.tar.gz: d82e2faf6d565f8be930ca24e9c3af7b60de23c8ed02dbcc0d14390c6725580b
+  metadata.gz: 96812d57f991f56ae85d042ed90d67cd804da41be917f557c9035b7103704fa0
+  data.tar.gz: ba04b33847262251dbce411840acee273e7f36c3f25e3b02a6fd2aaacf88bbe9
 SHA512:
-  metadata.gz: 656e243f281d61d4afac21dfdd2f18be27659ae695bc5d6770146fc7e234135a21e221847157d75bb50b1d41d2798094e87868fc8d91cac1eee0fe38e651c6eb
-  data.tar.gz: b65f741d51b2b192c2456356081ad908145d68f93d37e64c6ba5d45c3ae838820120d7c852592dd60d1f3da54e2bf21e88316bede5c2e9971d0af24d2cecbe50
+  metadata.gz: 587ba80330156dc5a305ea2d92831939fa9f80b6341bdb1052d639d371b8892d9827ddd0ce24b4b07c0c67714aec87151dcc31bc515031aee055a10703d3bf0f
+  data.tar.gz: 8dfe3c3526d621ee904535484e70529c68550d2388f289408a40f044651f154f6cb424f8715967d3d9dcaf8aa652f48bdb0ddda1e505c882c37f8fe01c9a1dbc

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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-384%20passing-brightgreen)](https://github.com/yourusername/better_seo)
+[![Coverage](https://img.shields.io/badge/coverage-99.71%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.5.0)
 
 - **Core Configuration System**
   - Singleton configuration with block-style setup
@@ -38,23 +38,33 @@ 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
+
 ### 🚧 Planned
 
-- **Advanced Generators** (v0.5.0)
+- **Advanced Generators** (v0.6.0)
   - Schema.org JSON-LD generator
   - Breadcrumbs generator
   - AMP HTML generator
 
-- **Advanced Rails Integration** (v0.5.0)
+- **Advanced Rails Integration** (v0.6.0)
   - Controller helpers for setting page SEO
   - Railtie for automatic initialization
   - Generator for initializer file
 
-- **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.6.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 +74,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.5.0'
 ```
 
 And then execute:
@@ -82,6 +94,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.5.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.5.0.gem
+```
+
 ## Quick Start
 
 ### 1. Configuration
@@ -555,6 +584,442 @@ 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
+```
+
 ## 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.5.0"
 end

data/lib/better_seo.rb

@@ -14,6 +14,9 @@ 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"
 
 module BetterSeo
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_seo
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - alessiobussolari
@@ -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: []