better_seo 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c99ac27d15378d081160acc05a0cfa384a32f732deb452e3ba404d13b040ca7
-  data.tar.gz: a7f07d8267cdc57c2a09f86e7c26167fc7c1f23c3ef73df944aa6bc6bc8a87e0
+  metadata.gz: 42834acb5d5dca21a12b20288b28544bd5112aac2fe8a05dbf3123707f1f21fe
+  data.tar.gz: 8efa2fd4287fbf0078d57691148c2cdc78e2f03a18c5af2eb96fc6819d32c5d6
 SHA512:
-  metadata.gz: 413a2b9f1342f61fe4b5f26f22a6f9d3152f775699bdc51f105aa77e5740ac78030da6ae06ba6397b2372fb996e8d343a52469a972bb6996d67f9358c4ca7dfc
-  data.tar.gz: 1bf40ac3c4e21559eda6cb663f44c8aaef5b2ed8c58e43a06b44028df9f1833d908eb0c44159ec12c467c7b3c6ea7001b2ebc188ba27a06de81d95c34e06bbef
+  metadata.gz: 934a6db489cbda29d885011c889d268b66858b9d202d5c561907543365a639547c7e9bc39cd2dc0acc529e4fba4c9f9eb21de10fb76cdb7211c15c4622249073
+  data.tar.gz: d5ceb959972b3e687140a87c87c649525d0844abaffb1ddd316259eaa4cd82b7b5780152a92e06120c8ab7ff46fdce33f1c2449f8f225321a92958f87d8895bc

data/CHANGELOG.md

@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2025-01-23
+
+### Added
+- Advanced SEO Tools for validation and content management
+  - **Robots.txt Generator** (`BetterSeo::Generators::RobotsTxtGenerator`)
+    - `add_rule(user_agent, allow:, disallow:)` - Add robot directives
+    - `set_crawl_delay(user_agent, seconds)` - Set crawl delay for bots
+    - `add_sitemap(url)` - Add sitemap references
+    - `clear` - Remove all rules and sitemaps
+    - `to_text` - Generate robots.txt content
+    - `write_to_file(path)` - Write robots.txt to file
+    - Support for multiple user agents (*, Googlebot, Bingbot, etc.)
+    - Allow/Disallow path directives
+    - Automatic directory creation
+    - Method chaining for fluent API
+  - **SEO Validator** (`BetterSeo::Validators::SeoValidator`)
+    - `check_title(text)` - Validate title length (30-60 chars optimal)
+    - `check_description(text)` - Validate description length (120-160 chars optimal)
+    - `check_headings(html)` - Validate H1-H6 structure
+    - `check_images(html)` - Validate image alt text presence
+    - `validate_page(html)` - Complete page validation
+    - `generate_report(validation)` - Human-readable SEO report
+    - Overall SEO score (0-100) with weighted components
+    - Detailed issue tracking and recommendations
+    - Warning levels for sub-optimal content
+    - HTML parsing for meta tags extraction
+
+### Enhanced
+- Validators module introduced for SEO quality checks
+- Comprehensive validation rules following SEO best practices
+- Detailed error messages with actionable recommendations
+
+### Test Coverage
+- 858 tests passing (+47 from v0.12.0)
+- 96.7% code coverage (1668/1725 lines)
+- 47 new tests across SEO tools:
+  - Robots.txt Generator: 25 tests
+  - SEO Validator: 22 tests
+
+## [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-858%20passing-brightgreen)](https://github.com/yourusername/better_seo)
+[![Coverage](https://img.shields.io/badge/coverage-96.7%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.13.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,462 @@ 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"
+```
+
+---
+
+## SEO Tools
+
+### Robots.txt Generator
+
+Generate robots.txt files to control search engine crawler access.
+
+#### Basic Usage
+
+```ruby
+robots = BetterSeo::Generators::RobotsTxtGenerator.new
+
+# Allow all bots except specific paths
+robots.add_rule("*", disallow: ["/admin", "/api/private", "/tmp"])
+
+# Add sitemap
+robots.add_sitemap("https://example.com/sitemap.xml")
+
+# Generate robots.txt content
+text = robots.to_text
+# User-agent: *
+# Disallow: /admin
+# Disallow: /api/private
+# Disallow: /tmp
+#
+# Sitemap: https://example.com/sitemap.xml
+```
+
+#### Multiple User Agents
+
+```ruby
+robots = BetterSeo::Generators::RobotsTxtGenerator.new
+
+# Rules for all bots
+robots.add_rule("*", allow: "/", disallow: "/admin")
+
+# Specific rules for Googlebot
+robots.add_rule("Googlebot", allow: "/api/public", disallow: "/temp")
+
+# Crawl delay for aggressive bots
+robots.add_rule("Bingbot", disallow: "/admin")
+robots.set_crawl_delay("Bingbot", 2)
+
+text = robots.to_text
+```
+
+#### Write to File
+
+```ruby
+robots = BetterSeo::Generators::RobotsTxtGenerator.new
+robots.add_rule("*", disallow: ["/admin", "/private"])
+robots.add_sitemap("https://example.com/sitemap.xml")
+
+# Write to public directory
+robots.write_to_file(Rails.root.join('public', 'robots.txt'))
+```
+
+#### Rails Controller Integration
+
+```ruby
+# app/controllers/robots_controller.rb
+class RobotsController < ApplicationController
+  def index
+    robots = BetterSeo::Generators::RobotsTxtGenerator.new
+
+    if Rails.env.production?
+      robots.add_rule("*", disallow: ["/admin", "/api/private"])
+      robots.add_sitemap("#{request.base_url}/sitemap.xml")
+    else
+      # Block all bots in non-production
+      robots.add_rule("*", disallow: "/")
+    end
+
+    render plain: robots.to_text, content_type: "text/plain"
+  end
+end
+
+# config/routes.rb
+get '/robots.txt', to: 'robots#index'
+```
+
+---
+
+### SEO Validator
+
+Validate and score your pages for SEO best practices.
+
+#### Basic Usage
+
+```ruby
+validator = BetterSeo::Validators::SeoValidator.new
+
+# Check individual elements
+title_result = validator.check_title("My Awesome SEO-Friendly Page Title")
+# => { valid: true, score: 100, message: "Title length is optimal", length: 35 }
+
+desc_result = validator.check_description("This is a comprehensive meta description...")
+# => { valid: true, score: 100, message: "Description length is optimal", length: 145 }
+```
+
+#### Validate Complete Page
+
+```ruby
+validator = BetterSeo::Validators::SeoValidator.new
+
+html = <<~HTML
+  <!DOCTYPE html>
+  <html>
+  <head>
+    <title>Best Ruby SEO Gem for Rails Applications</title>
+    <meta name="description" content="BetterSeo provides comprehensive SEO tools for Ruby on Rails including meta tags, structured data, sitemaps, and validators.">
+  </head>
+  <body>
+    <h1>BetterSeo: Complete SEO Solution</h1>
+    <img src="logo.png" alt="BetterSeo Logo">
+    <h2>Features</h2>
+    <h2>Getting Started</h2>
+  </body>
+  </html>
+HTML
+
+result = validator.validate_page(html)
+# => {
+#   overall_score: 95,
+#   title: { valid: true, score: 100, ... },
+#   description: { valid: true, score: 100, ... },
+#   headings: { valid: true, score: 100, h1_count: 1, ... },
+#   images: { valid: true, score: 100, ... },
+#   issues: []
+# }
+```
+
+#### Generate SEO Report
+
+```ruby
+validator = BetterSeo::Validators::SeoValidator.new
+result = validator.validate_page(html)
+
+report = validator.generate_report(result)
+puts report
+# ============================================================
+# SEO Validation Report
+# ============================================================
+#
+# Overall Score: 95/100
+#
+# Title:
+#   Status: ✓
+#   Score: 100/100
+#   Length: 45 chars
+#   Message: Title length is optimal
+#
+# Description:
+#   Status: ✓
+#   Score: 100/100
+#   ...
+```
+
+#### Rails Integration
+
+```ruby
+# app/services/seo_validator_service.rb
+class SeoValidatorService
+  def self.validate_page_seo(url)
+    html = fetch_page_html(url)
+    validator = BetterSeo::Validators::SeoValidator.new
+    validator.validate_page(html)
+  end
+
+  def self.audit_site
+    pages = Page.published.pluck(:url)
+    validator = BetterSeo::Validators::SeoValidator.new
+
+    results = pages.map do |url|
+      html = fetch_page_html(url)
+      validation = validator.validate_page(html)
+      { url: url, score: validation[:overall_score], issues: validation[:issues] }
+    end
+
+    results.sort_by { |r| r[:score] }
+  end
+end
+```
+
+#### Validation Rules
+
+- **Title**: 30-60 characters optimal
+- **Description**: 120-160 characters optimal
+- **Headings**: Exactly one H1 tag required
+- **Images**: All images must have alt text
+- **Overall Score**: Weighted average (Title: 30%, Description: 30%, Headings: 20%, Images: 20%)
+
+---
+
 ## 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.13.0"
 end

data/lib/better_seo.rb

@@ -13,6 +13,11 @@ 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/generators/robots_txt_generator"
+require_relative "better_seo/validators/seo_validator"
 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.13.0
 platform: ruby
 authors:
 - alessiobussolari