better_seo 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 181be2cb7b7341c4b6d304b2d093351f0259212d880406d1a3673e1ceb4dbd98
-  data.tar.gz: 812c35ed74e6250712fa668abbe8274069e601bc5d9bb342283e95061c5f7d83
+  metadata.gz: bbb87756b71cdc491faaba16bd349149051ef870ac1eea6dab55c31db3e09bd9
+  data.tar.gz: b34bc18d112710290991d430ff5525b920dadc25938aed97a6e20a3309118d45
 SHA512:
-  metadata.gz: 546233d6a80cc7780d642fd6cf96dcc2ee931dbc39a444a9fc224173579af8a7e8235f9a588a5d212f31c5930c0d6f007fc778090c11baca021ffb690c8b85aa
-  data.tar.gz: 4d2620e7b9c8b517d4c412b24b7f7b0b7e3aaf76d4c16f8b9c29357fb9517f1a85225b4130f816902553a0800db0f1aa51999120c07ea6973c138ebfbee7c9a7
+  metadata.gz: ca7e8d51f6c035725975a2326908156c0e6c5281d4ded7a10fd709775e4aa44208a5a609589fbbaf66c62ef0f54ab4f024b5a685001ab472cb2d1e0bb24097a2
+  data.tar.gz: b353b67665a36f045d2db900d3285996d021ec19db9b5ac7c1fd697ecfa5c4082fc895a3517190f70c79ae7f4f78d9290ab0f79034c3ecdc2da6ad490df20436

data/CHANGELOG.md

@@ -7,6 +7,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2025-01-23
+
+### Added
+- Advanced HTML Generators for modern web applications
+  - **BreadcrumbsGenerator** (`BetterSeo::Generators::BreadcrumbsGenerator`)
+    - `add_item(name, url)` - Add single breadcrumb item
+    - `add_items(array)` - Add multiple items at once
+    - `clear` - Remove all items
+    - `to_html(schema:, nav_class:, list_class:)` - Generate HTML breadcrumbs
+    - `to_json_ld` - Generate JSON-LD structured data
+    - `to_script_tag` - Generate script tag with JSON-LD
+    - Schema.org microdata support with `schema: true` option
+    - Custom CSS classes for nav and list elements
+    - Automatic position numbering for structured data
+    - Current page support (items without URLs)
+    - HTML entity escaping for security
+  - **AMP Generator** (`BetterSeo::Generators::AmpGenerator`)
+    - `to_boilerplate` - Generate required AMP boilerplate CSS
+    - `to_amp_script_tag` - Generate AMP runtime script tag
+    - `to_meta_tags` - Generate canonical and OG meta tags
+    - `to_structured_data` - Generate JSON-LD script tag
+    - `to_custom_css(css)` - Wrap custom CSS in amp-custom style tag
+    - Support for canonical URL, title, description, image
+    - Structured data integration for AMP pages
+    - Complete AMP HTML page support
+  - **Canonical URL Manager** (`BetterSeo::Generators::CanonicalUrlManager`)
+    - `to_html` - Generate canonical link HTML tag
+    - `to_http_header` - Generate Link HTTP header
+    - `validate!` - Validate canonical URL format and structure
+    - URL normalization features:
+      - Remove trailing slashes (preserves root URL)
+      - Remove fragment identifiers automatically
+      - Optional query parameter removal
+      - Optional URL lowercasing
+    - Validation for absolute URLs only
+    - HTTP/HTTPS protocol validation
+    - HTML entity escaping
+
+### Enhanced
+- HTML Generators section in README with comprehensive examples
+- Documentation for all three new generators
+- Rails integration examples for each generator
+
+### Test Coverage
+- 811 tests passing (+69 from v0.11.0)
+- 96.41% code coverage (1506/1562 lines)
+- 69 new tests across advanced generators:
+  - BreadcrumbsGenerator: 21 tests
+  - AMP Generator: 22 tests
+  - Canonical URL Manager: 26 tests
+
+## [0.11.0] - 2025-01-23
+
+### Added
+- Advanced Sitemap Features for large and international sites
+  - **Multi-language Support (hreflang)**
+    - `UrlEntry#add_alternate(href, hreflang:)` - Add alternate language versions
+    - Support for region-specific alternates (en-US, en-GB, etc.)
+    - x-default alternate support for default language
+    - Automatic xhtml:link tag generation in XML
+    - Method chaining for adding multiple alternates
+  - **Image Sitemap Extensions**
+    - `UrlEntry#add_image(loc, title:, caption:)` - Add images to URLs
+    - Support for multiple images per URL
+    - Automatic image:image tag generation
+    - Optional title and caption metadata
+  - **Video Sitemap Extensions**
+    - `UrlEntry#add_video(thumbnail_loc:, title:, description:, content_loc:, duration:)` - Add videos to URLs
+    - Support for multiple videos per URL
+    - Automatic video:video tag generation
+    - Optional duration metadata
+  - **Sitemap Index** (`BetterSeo::Sitemap::SitemapIndex`)
+    - Manage large sites with 50,000+ URLs
+    - Split sitemaps across multiple files
+    - `add_sitemap(loc, lastmod:)` - Add sitemaps to index
+    - `to_xml` - Generate sitemapindex XML
+    - `write_to_file(path)` - Write index to file
+    - Automatic directory creation
+
+### Enhanced
+- `UrlEntry` now supports alternates, images, and videos arrays
+- `UrlEntry#to_xml` includes all extensions (hreflang, images, videos)
+- `UrlEntry#to_h` includes alternates when present
+
+### Test Coverage
+- 742 tests passing (+35 from v0.10.0)
+- 96.12% code coverage (1364/1419 lines)
+- 35 new tests across advanced sitemap features:
+  - Hreflang support: 11 tests
+  - SitemapIndex: 12 tests
+  - Image/Video extensions: 12 tests
+
 ## [0.10.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-707%20passing-brightgreen)](https://github.com/yourusername/better_seo)
-[![Coverage](https://img.shields.io/badge/coverage-95.99%25-brightgreen)](https://github.com/yourusername/better_seo)
+[![Tests](https://img.shields.io/badge/tests-811%20passing-brightgreen)](https://github.com/yourusername/better_seo)
+[![Coverage](https://img.shields.io/badge/coverage-96.41%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.10.0)
+### ✅ Implemented (v0.12.0)
 
 - **Core Configuration System**
   - Singleton configuration with block-style setup
@@ -25,10 +25,13 @@ A comprehensive SEO gem for Ruby and Rails applications. BetterSeo provides a cl
   - Fluent interface with method chaining
   - Automatic validation (title/description length, required fields)
 
-- **HTML Generators**
+- **HTML Generators** - Advanced generators for modern web
   - **MetaTagsGenerator**: Converts DSL to HTML meta tags
   - **OpenGraphGenerator**: Converts DSL to Open Graph meta tags
   - **TwitterCardsGenerator**: Converts DSL to Twitter Card meta tags
+  - **BreadcrumbsGenerator**: HTML breadcrumb navigation with Schema.org support
+  - **AMP Generator**: Accelerated Mobile Pages (AMP) support
+  - **Canonical URL Manager**: Canonical URL normalization and management
   - HTML entity escaping for security
   - Integration with DSL builders
 
@@ -43,10 +46,14 @@ 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**
+- **Sitemap Generation** - Advanced features for large sites
   - **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)
+  - **Multi-language Support**: hreflang alternates for international sites
+  - **Image Sitemaps**: Add images with title and caption to URLs
+  - **Video Sitemaps**: Add videos with thumbnail, title, description, duration
+  - **Sitemap Index**: Manage large sites with 50,000+ URLs across multiple sitemaps
   - **Dynamic Generation**: Lambda support for dynamic attributes
   - **File Writing**: Write sitemaps directly to files
   - **Rails Integration**: Controller actions and Rake tasks
@@ -72,22 +79,11 @@ A comprehensive SEO gem for Ruby and Rails applications. BetterSeo provides a cl
 
 ### 🚧 Planned
 
-- **Advanced Generators** (v1.1.0)
-  - Breadcrumbs HTML generator
-  - AMP HTML generator
-  - Canonical URL management
-
-- **Advanced Sitemap Features** (v1.1.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+)
+- **Advanced Features** (v0.13.0+)
   - robots.txt generator
   - Image optimization with WebP conversion
-  - Structured data builders (Organization, Person, Product, etc.)
   - SEO validators and recommendations
+  - Performance monitoring and analytics integration
 
 ## Installation
 
@@ -1534,6 +1530,269 @@ all_tags = BetterSeo::StructuredData::Generator.generate_script_tags([
 - **Standards Compliant**: Follows Schema.org specifications
 - **Easy Integration**: Works seamlessly with Rails views and helpers
 
+---
+
+## Advanced Generators
+
+### Breadcrumbs Generator
+
+Generate HTML breadcrumb navigation with Schema.org structured data support.
+
+#### Basic Usage
+
+```ruby
+generator = BetterSeo::Generators::BreadcrumbsGenerator.new
+generator.add_item("Home", "/")
+generator.add_item("Products", "/products")
+generator.add_item("Laptops", "/products/laptops")
+generator.add_item("MacBook Pro", nil) # Current page (no link)
+
+# Generate HTML breadcrumbs
+html = generator.to_html
+# <nav class="breadcrumb" aria-label="breadcrumb">
+#   <ol class="breadcrumb">
+#     <li class="breadcrumb-item">
+#       <a href="/">Home</a>
+#     </li>
+#     ...
+#   </ol>
+# </nav>
+
+# Generate JSON-LD structured data
+json_ld = generator.to_json_ld
+script_tag = generator.to_script_tag
+```
+
+#### With Schema.org Markup
+
+```ruby
+# Generate breadcrumbs with microdata
+html = generator.to_html(schema: true)
+# Includes itemscope, itemtype, itemprop attributes for rich snippets
+```
+
+#### Custom Styling
+
+```ruby
+html = generator.to_html(
+  nav_class: "my-breadcrumb-nav",
+  list_class: "my-breadcrumb-list"
+)
+```
+
+#### Rails Integration
+
+```erb
+<!-- app/views/layouts/application.html.erb -->
+<%
+  breadcrumbs = BetterSeo::Generators::BreadcrumbsGenerator.new
+  breadcrumbs.add_item("Home", root_path)
+  breadcrumbs.add_item("Blog", blog_path)
+  breadcrumbs.add_item(@post.title, nil)
+%>
+
+<%= raw breadcrumbs.to_html(schema: true) %>
+<%= raw breadcrumbs.to_script_tag %>
+```
+
+#### Multiple Items at Once
+
+```ruby
+generator.add_items([
+  { name: "Home", url: "/" },
+  { name: "Products", url: "/products" },
+  { name: "Laptops", url: "/products/laptops" }
+])
+```
+
+---
+
+### AMP Generator
+
+Generate Accelerated Mobile Pages (AMP) HTML components.
+
+#### Basic Usage
+
+```ruby
+amp = BetterSeo::Generators::AmpGenerator.new(
+  canonical_url: "https://example.com/article",
+  title: "My Article Title",
+  description: "Article description",
+  image: "https://example.com/image.jpg"
+)
+
+# AMP boilerplate CSS
+boilerplate = amp.to_boilerplate
+
+# AMP runtime script
+amp_script = amp.to_amp_script_tag
+# <script async src="https://cdn.ampproject.org/v0.js"></script>
+
+# Meta tags
+meta_tags = amp.to_meta_tags
+# Includes canonical, og:title, og:description, og:image
+```
+
+#### Complete AMP Page
+
+```erb
+<!doctype html>
+<html ⚡>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
+
+  <%= raw amp.to_meta_tags %>
+  <%= raw amp.to_amp_script_tag %>
+  <%= raw amp.to_boilerplate %>
+
+  <% custom_css = "body { font-family: Arial; } h1 { color: #333; }" %>
+  <%= raw amp.to_custom_css(custom_css) %>
+</head>
+<body>
+  <!-- Your AMP content -->
+</body>
+</html>
+```
+
+#### With Structured Data
+
+```ruby
+article_data = {
+  "@context" => "https://schema.org",
+  "@type" => "Article",
+  "headline" => "My Article",
+  "author" => { "@type" => "Person", "name" => "John Doe" }
+}
+
+amp.structured_data = article_data
+script = amp.to_structured_data
+# <script type="application/ld+json">
+# { "@context": "https://schema.org", "@type": "Article", ... }
+# </script>
+```
+
+#### Rails Controller Integration
+
+```ruby
+class ArticlesController < ApplicationController
+  def amp
+    @article = Article.find(params[:id])
+
+    @amp = BetterSeo::Generators::AmpGenerator.new(
+      canonical_url: article_url(@article),
+      title: @article.title,
+      description: @article.excerpt,
+      image: @article.featured_image_url
+    )
+
+    render layout: 'amp'
+  end
+end
+```
+
+---
+
+### Canonical URL Manager
+
+Manage and normalize canonical URLs with validation.
+
+#### Basic Usage
+
+```ruby
+manager = BetterSeo::Generators::CanonicalUrlManager.new("https://example.com/page")
+
+# Generate HTML link tag
+html = manager.to_html
+# <link rel="canonical" href="https://example.com/page">
+
+# Generate HTTP header
+header = manager.to_http_header
+# <https://example.com/page>; rel="canonical"
+
+# Validate URL
+manager.validate! # Raises ValidationError if invalid
+```
+
+#### URL Normalization
+
+```ruby
+manager = BetterSeo::Generators::CanonicalUrlManager.new
+
+# Removes trailing slashes
+manager.url = "https://example.com/page/"
+manager.url # => "https://example.com/page"
+
+# Removes fragment identifiers
+manager.url = "https://example.com/page#section"
+manager.url # => "https://example.com/page"
+
+# Optional: Remove query parameters
+manager.remove_query_params = true
+manager.url = "https://example.com/page?utm_source=twitter&ref=123"
+manager.url # => "https://example.com/page"
+
+# Optional: Lowercase URL
+manager.lowercase = true
+manager.url = "https://Example.com/Page"
+manager.url # => "https://example.com/page"
+```
+
+#### Rails Integration
+
+```ruby
+# Controller
+class ArticlesController < ApplicationController
+  def show
+    @article = Article.find(params[:id])
+
+    canonical = BetterSeo::Generators::CanonicalUrlManager.new
+    canonical.remove_query_params = true
+    canonical.url = article_url(@article)
+
+    response.headers['Link'] = canonical.to_http_header
+    @canonical_tag = canonical.to_html
+  end
+end
+
+# View (app/views/articles/show.html.erb)
+<head>
+  <%= raw @canonical_tag %>
+</head>
+```
+
+#### Advanced Normalization
+
+```ruby
+manager = BetterSeo::Generators::CanonicalUrlManager.new
+manager.remove_query_params = true
+manager.lowercase = true
+manager.url = "https://Example.com/Page/?utm_source=google#section"
+
+manager.url # => "https://example.com/page"
+manager.validate! # => true
+```
+
+#### Error Handling
+
+```ruby
+manager = BetterSeo::Generators::CanonicalUrlManager.new
+
+# Relative URLs not allowed
+manager.url = "/page"
+manager.validate! # Raises: "Canonical URL must be absolute: /page"
+
+# Invalid URL format
+manager.url = "not a url"
+manager.validate! # Raises: "Invalid URL format: not a url"
+
+# URL is required
+manager.url = nil
+manager.validate! # Raises: "URL is required"
+```
+
+---
+
 ## Configuration Reference
 
 ### Global Configuration
@@ -1643,13 +1902,13 @@ bundle exec rspec --format documentation
 ```
 
 Current test statistics:
-- **707 tests** passing
-- **95.99% code coverage** (1293/1347 lines)
+- **742 tests** passing
+- **96.12% code coverage** (1364/1419 lines)
 - **3 DSL builders** fully tested
 - **3 HTML generators** fully tested
 - **3 Rails helper modules** fully tested (View, Controller, Model)
 - **10 Structured data types** fully tested
-- **1 Sitemap generation system** fully tested
+- **1 Advanced sitemap system** with hreflang, images, videos, and index
 - **1 Railtie and Generator** fully tested
 - **1 core configuration system** fully tested
 

data/lib/better_seo/version.rb

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

data/lib/better_seo.rb

@@ -13,9 +13,13 @@ require_relative "better_seo/dsl/twitter_cards"
 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/generators/breadcrumbs_generator"
+require_relative "better_seo/generators/amp_generator"
+require_relative "better_seo/generators/canonical_url_manager"
 require_relative "better_seo/sitemap/url_entry"
 require_relative "better_seo/sitemap/builder"
 require_relative "better_seo/sitemap/generator"
+require_relative "better_seo/sitemap/sitemap_index"
 require_relative "better_seo/structured_data/base"
 require_relative "better_seo/structured_data/organization"
 require_relative "better_seo/structured_data/article"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_seo
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - alessiobussolari