better_seo 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c99ac27d15378d081160acc05a0cfa384a32f732deb452e3ba404d13b040ca7
-  data.tar.gz: a7f07d8267cdc57c2a09f86e7c26167fc7c1f23c3ef73df944aa6bc6bc8a87e0
+  metadata.gz: bbb87756b71cdc491faaba16bd349149051ef870ac1eea6dab55c31db3e09bd9
+  data.tar.gz: b34bc18d112710290991d430ff5525b920dadc25938aed97a6e20a3309118d45
 SHA512:
-  metadata.gz: 413a2b9f1342f61fe4b5f26f22a6f9d3152f775699bdc51f105aa77e5740ac78030da6ae06ba6397b2372fb996e8d343a52469a972bb6996d67f9358c4ca7dfc
-  data.tar.gz: 1bf40ac3c4e21559eda6cb663f44c8aaef5b2ed8c58e43a06b44028df9f1833d908eb0c44159ec12c467c7b3c6ea7001b2ebc188ba27a06de81d95c34e06bbef
+  metadata.gz: ca7e8d51f6c035725975a2326908156c0e6c5281d4ded7a10fd709775e4aa44208a5a609589fbbaf66c62ef0f54ab4f024b5a685001ab472cb2d1e0bb24097a2
+  data.tar.gz: b353b67665a36f045d2db900d3285996d021ec19db9b5ac7c1fd697ecfa5c4082fc895a3517190f70c79ae7f4f78d9290ab0f79034c3ecdc2da6ad490df20436

data/CHANGELOG.md

@@ -7,6 +7,57 @@ 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

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-742%20passing-brightgreen)](https://github.com/yourusername/better_seo)
-[![Coverage](https://img.shields.io/badge/coverage-96.12%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.11.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
 
@@ -76,16 +79,11 @@ A comprehensive SEO gem for Ruby and Rails applications. BetterSeo provides a cl
 
 ### 🚧 Planned
 
-- **Advanced Generators** (v1.0.0)
-  - Breadcrumbs HTML generator
-  - AMP HTML generator
-  - Canonical URL management
-
-- **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
 
@@ -1532,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

data/lib/better_seo/version.rb

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

data/lib/better_seo.rb

@@ -13,6 +13,9 @@ 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"

metadata

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