better_seo 0.14.0 → 1.0.0.1

data/lib/better_seo/validators/seo_recommendations.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module BetterSeo
+  module Validators
+    class SeoRecommendations
+      def generate_recommendations(validation_result)
+        recommendations = []
+
+        recommendations += recommend_title_improvements(validation_result[:title])
+        recommendations += recommend_description_improvements(validation_result[:description])
+        recommendations += recommend_heading_improvements(validation_result[:headings])
+        recommendations += recommend_image_improvements(validation_result[:images])
+
+        # Sort by priority: high, medium, low
+        priority_order = { high: 0, medium: 1, low: 2 }
+        recommendations.sort_by { |r| priority_order[r[:priority]] }
+      end
+
+      def recommend_title_improvements(title_result)
+        return [] if title_result[:valid]
+
+        recommendations = []
+        length = title_result[:length]
+
+        if length == 0
+          recommendations << {
+            category: "Title",
+            priority: :high,
+            action: "Add a page title",
+            details: "A title tag is required for SEO. Aim for 30-60 characters."
+          }
+        elsif length < 30
+          needed = 30 - length
+          recommendations << {
+            category: "Title",
+            priority: :high,
+            action: "Make title longer",
+            details: "Add approximately #{needed} more characters to reach the optimal length (30-60 chars)."
+          }
+        elsif length > 60
+          excess = length - 60
+          recommendations << {
+            category: "Title",
+            priority: :medium,
+            action: "Make title shorter",
+            details: "Reduce by approximately #{excess} characters to stay within optimal length (30-60 chars)."
+          }
+        end
+
+        recommendations
+      end
+
+      def recommend_description_improvements(desc_result)
+        return [] if desc_result[:valid]
+
+        recommendations = []
+        length = desc_result[:length]
+
+        if length == 0
+          recommendations << {
+            category: "Meta Description",
+            priority: :high,
+            action: "Add a meta description",
+            details: "Meta descriptions help search engines understand your content. Aim for 120-160 characters."
+          }
+        elsif length < 120
+          needed = 120 - length
+          recommendations << {
+            category: "Meta Description",
+            priority: :medium,
+            action: "Add more detail to description",
+            details: "Add approximately #{needed} more characters to provide more context (optimal: 120-160 chars)."
+          }
+        elsif length > 160
+          excess = length - 160
+          recommendations << {
+            category: "Meta Description",
+            priority: :medium,
+            action: "Condense description",
+            details: "Reduce by approximately #{excess} characters to prevent truncation in search results."
+          }
+        end
+
+        recommendations
+      end
+
+      def recommend_heading_improvements(headings_result)
+        return [] if headings_result[:valid]
+
+        recommendations = []
+        h1_count = headings_result[:h1_count]
+
+        if h1_count == 0
+          recommendations << {
+            category: "Headings",
+            priority: :high,
+            action: "Add an H1 heading",
+            details: "Every page should have exactly one H1 tag that describes the main topic."
+          }
+        elsif h1_count > 1
+          recommendations << {
+            category: "Headings",
+            priority: :high,
+            action: "Use only one H1 heading",
+            details: "Found #{h1_count} H1 tags. Use H2-H6 for subheadings instead."
+          }
+        end
+
+        if headings_result[:total_headings] == 0
+          recommendations << {
+            category: "Headings",
+            priority: :medium,
+            action: "Add heading structure",
+            details: "Use headings (H1-H6) to organize content and improve readability."
+          }
+        end
+
+        recommendations
+      end
+
+      def recommend_image_improvements(images_result)
+        return [] if images_result[:valid]
+
+        recommendations = []
+
+        if images_result[:images_without_alt] > 0
+          count = images_result[:images_without_alt]
+          recommendations << {
+            category: "Images",
+            priority: :medium,
+            action: "Add alt text to images",
+            details: "#{count} image#{count > 1 ? 's' : ''} missing alt text. Alt text improves accessibility and SEO."
+          }
+        end
+
+        recommendations
+      end
+
+      def format_recommendations(recommendations)
+        return "# SEO Recommendations\n\nNo recommendations - your SEO is optimal! ✓" if recommendations.empty?
+
+        output = []
+        output << "# SEO Recommendations\n"
+
+        # Group by priority
+        grouped = recommendations.group_by { |r| r[:priority] }
+
+        [:high, :medium, :low].each do |priority|
+          next unless grouped[priority]
+
+          output << "## #{priority.to_s.capitalize} Priority\n"
+
+          grouped[priority].each do |rec|
+            output << "### #{rec[:category]}"
+            output << "**Action:** #{rec[:action]}\n"
+            output << "**Details:** #{rec[:details]}\n" if rec[:details]
+            output << ""
+          end
+        end
+
+        output.join("\n")
+      end
+    end
+  end
+end

data/lib/better_seo/validators/seo_validator.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module BetterSeo
+  module Validators
+    class SeoValidator
+      TITLE_MIN_LENGTH = 30
+      TITLE_MAX_LENGTH = 60
+      DESCRIPTION_MIN_LENGTH = 120
+      DESCRIPTION_MAX_LENGTH = 160
+
+      def check_title(title)
+        return { valid: false, score: 0, message: "Title is required", length: 0 } if title.nil? || title.empty?
+
+        length = title.length
+
+        if length >= TITLE_MIN_LENGTH && length <= TITLE_MAX_LENGTH
+          { valid: true, score: 100, message: "Title length is optimal", length: length }
+        elsif length < TITLE_MIN_LENGTH
+          score = (length.to_f / TITLE_MIN_LENGTH * 70).to_i
+          { valid: false, score: score, message: "Title is too short (minimum #{TITLE_MIN_LENGTH} characters recommended)", length: length }
+        else
+          score = [100 - (length - TITLE_MAX_LENGTH) * 2, 50].max
+          { valid: false, score: score, message: "Title is too long (maximum #{TITLE_MAX_LENGTH} characters recommended)", length: length }
+        end
+      end
+
+      def check_description(description)
+        return { valid: false, score: 0, message: "Description is required", length: 0 } if description.nil? || description.empty?
+
+        length = description.length
+
+        if length >= DESCRIPTION_MIN_LENGTH && length <= DESCRIPTION_MAX_LENGTH
+          { valid: true, score: 100, message: "Description length is optimal", length: length }
+        elsif length < DESCRIPTION_MIN_LENGTH
+          score = (length.to_f / DESCRIPTION_MIN_LENGTH * 70).to_i
+          { valid: false, score: score, message: "Description is too short (minimum #{DESCRIPTION_MIN_LENGTH} characters recommended)", length: length }
+        else
+          score = [100 - (length - DESCRIPTION_MAX_LENGTH), 50].max
+          { valid: false, score: score, message: "Description is too long (maximum #{DESCRIPTION_MAX_LENGTH} characters recommended)", length: length }
+        end
+      end
+
+      def check_headings(html)
+        h1_count = html.scan(/<h1[^>]*>/).size
+        h2_count = html.scan(/<h2[^>]*>/).size
+        h3_count = html.scan(/<h3[^>]*>/).size
+        h4_count = html.scan(/<h4[^>]*>/).size
+        h5_count = html.scan(/<h5[^>]*>/).size
+        h6_count = html.scan(/<h6[^>]*>/).size
+
+        total = h1_count + h2_count + h3_count + h4_count + h5_count + h6_count
+
+        result = {
+          h1_count: h1_count,
+          h2_count: h2_count,
+          h3_count: h3_count,
+          total_headings: total
+        }
+
+        if h1_count == 0
+          result.merge(valid: false, score: 50, message: "Missing H1 heading (exactly one H1 required)")
+        elsif h1_count > 1
+          result.merge(valid: false, score: 70, message: "Multiple H1 headings found (only one H1 recommended)")
+        elsif total == 0
+          result.merge(valid: false, score: 0, message: "No headings found")
+        else
+          result.merge(valid: true, score: 100, message: "Heading structure is optimal")
+        end
+      end
+
+      def check_images(html)
+        # Find all img tags
+        images = html.scan(/<img[^>]*>/)
+        total = images.size
+
+        return { valid: true, score: 100, total_images: 0, images_with_alt: 0, images_without_alt: 0, message: "No images to validate" } if total.zero?
+
+        # Count images with alt text
+        images_with_alt = images.count { |img| img =~ /alt=["'][^"']+["']/ }
+        images_without_alt = total - images_with_alt
+
+        result = {
+          total_images: total,
+          images_with_alt: images_with_alt,
+          images_without_alt: images_without_alt
+        }
+
+        if images_without_alt.zero?
+          result.merge(valid: true, score: 100, message: "All images have alt text")
+        else
+          score = (images_with_alt.to_f / total * 100).to_i
+          result.merge(valid: false, score: score, message: "#{images_without_alt} image(s) missing alt text")
+        end
+      end
+
+      def validate_page(html)
+        # Extract title
+        title_match = html.match(/<title[^>]*>(.*?)<\/title>/m)
+        title = title_match ? title_match[1].strip : nil
+
+        # Extract meta description
+        desc_match = html.match(/<meta\s+name=["']description["']\s+content=["'](.*?)["']/i)
+        description = desc_match ? desc_match[1] : nil
+
+        # Run all checks
+        title_result = check_title(title)
+        description_result = check_description(description)
+        headings_result = check_headings(html)
+        images_result = check_images(html)
+
+        # Calculate overall score (weighted average)
+        overall_score = (
+          title_result[:score] * 0.3 +
+          description_result[:score] * 0.3 +
+          headings_result[:score] * 0.2 +
+          images_result[:score] * 0.2
+        ).to_i
+
+        # Collect issues
+        issues = []
+        issues << "Title: #{title_result[:message]}" unless title_result[:valid]
+        issues << "Description: #{description_result[:message]}" unless description_result[:valid]
+        issues << "Headings: #{headings_result[:message]}" unless headings_result[:valid]
+        issues << "Images: #{images_result[:message]}" unless images_result[:valid]
+
+        {
+          overall_score: overall_score,
+          title: title_result,
+          description: description_result,
+          headings: headings_result,
+          images: images_result,
+          issues: issues
+        }
+      end
+
+      def generate_report(validation)
+        report = []
+        report << "=" * 60
+        report << "SEO Validation Report"
+        report << "=" * 60
+        report << ""
+        report << "Overall Score: #{validation[:overall_score]}/100"
+        report << ""
+
+        # Title section
+        report << "Title:"
+        report << "  Status: #{validation[:title][:valid] ? '✓' : '✗'}"
+        report << "  Score: #{validation[:title][:score]}/100"
+        report << "  Length: #{validation[:title][:length]} chars"
+        report << "  Message: #{validation[:title][:message]}"
+        report << ""
+
+        # Description section
+        report << "Description:"
+        report << "  Status: #{validation[:description][:valid] ? '✓' : '✗'}"
+        report << "  Score: #{validation[:description][:score]}/100"
+        report << "  Length: #{validation[:description][:length]} chars"
+        report << "  Message: #{validation[:description][:message]}"
+        report << ""
+
+        # Headings section
+        report << "Headings:"
+        report << "  Status: #{validation[:headings][:valid] ? '✓' : '✗'}"
+        report << "  Score: #{validation[:headings][:score]}/100"
+        report << "  H1 Count: #{validation[:headings][:h1_count]}"
+        report << "  Total Headings: #{validation[:headings][:total_headings]}"
+        report << "  Message: #{validation[:headings][:message]}"
+        report << ""
+
+        # Images section
+        report << "Images:"
+        report << "  Status: #{validation[:images][:valid] ? '✓' : '✗'}"
+        report << "  Score: #{validation[:images][:score]}/100"
+        report << "  Total Images: #{validation[:images][:total_images]}"
+        report << "  With Alt: #{validation[:images][:images_with_alt]}"
+        report << "  Without Alt: #{validation[:images][:images_without_alt]}"
+        report << "  Message: #{validation[:images][:message]}"
+        report << ""
+
+        # Issues section
+        if validation[:issues].any?
+          report << "Issues:"
+          validation[:issues].each do |issue|
+            report << "  - #{issue}"
+          end
+          report << ""
+        end
+
+        report << "=" * 60
+
+        report.join("\n")
+      end
+    end
+  end
+end

data/lib/better_seo/version.rb

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

data/lib/better_seo.rb

@@ -42,6 +42,7 @@ require_relative "better_seo/rails/helpers/seo_helper"
 require_relative "better_seo/rails/helpers/structured_data_helper"
 require_relative "better_seo/rails/helpers/controller_helpers"
 require_relative "better_seo/rails/model_helpers"
+require_relative "better_seo/rails/railtie" if defined?(Rails::Railtie)
 
 module BetterSeo
   class << self

data/lib/generators/better_seo/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module BetterSeo
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a BetterSeo initializer file"
+
+      def copy_initializer
+        template "better_seo.rb", "config/initializers/better_seo.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/better_seo/templates/README

@@ -0,0 +1,29 @@
+===============================================================================
+
+BetterSeo has been installed successfully!
+
+Configuration file created at: config/initializers/better_seo.rb
+
+Next steps:
+
+1. Edit the configuration file to match your site settings
+2. Include BetterSeo::Rails::Helpers::ControllerHelpers in your controllers
+   (or use ApplicationController if you want it available everywhere)
+
+3. Use the helpers in your views:
+   - <%= seo_tags %> for complete SEO tags
+   - <%= seo_meta_tags %> for meta tags only
+   - <%= seo_open_graph_tags %> for Open Graph tags
+   - <%= seo_twitter_tags %> for Twitter Cards
+   - <%= structured_data_tag(:organization, ...) %> for structured data
+
+4. In your controllers, set page-specific SEO data:
+   - set_page_title("My Page")
+   - set_page_description("Description")
+   - set_page_keywords(["keyword1", "keyword2"])
+   - set_page_image("https://example.com/image.jpg")
+   - set_canonical("https://example.com/canonical-url")
+
+For more information, visit: https://github.com/alessiobussolari/better_seo
+
+===============================================================================

data/lib/generators/better_seo/templates/better_seo.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+BetterSeo.configure do |config|
+  # Site-wide settings
+  config.site_name = "My Site"
+  config.default_locale = :en
+  config.available_locales = [:en, :it, :fr, :de, :es]
+
+  # Meta tags configuration
+  config.meta_tags.default_title = "Default Title"
+  config.meta_tags.title_separator = " | "
+  config.meta_tags.append_site_name = true
+  config.meta_tags.default_description = "Default description for your website"
+  config.meta_tags.default_keywords = ["keyword1", "keyword2", "keyword3"]
+  config.meta_tags.default_author = "Your Name or Company"
+
+  # Open Graph configuration
+  config.open_graph.enabled = true
+  config.open_graph.site_name = "My Site"
+  config.open_graph.default_type = "website"
+  config.open_graph.default_locale = "en_US"
+  config.open_graph.default_image.url = "https://example.com/default-og-image.jpg"
+  config.open_graph.default_image.width = 1200
+  config.open_graph.default_image.height = 630
+  config.open_graph.default_image.alt = "Default image description"
+
+  # Twitter Cards configuration
+  config.twitter.enabled = true
+  config.twitter.site = "@yoursite"
+  config.twitter.creator = "@yourcreator"
+  config.twitter.card_type = "summary_large_image"
+
+  # Structured Data configuration
+  config.structured_data.enabled = true
+  # config.structured_data.organization = {
+  #   name: "My Organization",
+  #   url: "https://example.com",
+  #   logo: "https://example.com/logo.png"
+  # }
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: better_seo
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 1.0.0.1
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-23 00:00:00.000000000 Z
+date: 2025-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -82,8 +82,61 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/00_OVERVIEW.md
+- docs/01_CORE_AND_CONFIGURATION.md
+- docs/02_META_TAGS_AND_OPEN_GRAPH.md
+- docs/03_STRUCTURED_DATA.md
+- docs/04_SITEMAP_AND_ROBOTS.md
+- docs/05_RAILS_INTEGRATION.md
+- docs/06_I18N_PAGE_GENERATOR.md
+- docs/07_IMAGE_OPTIMIZATION.md
+- docs/DEPENDENCIES.md
+- docs/README.md
+- docs/TESTING_STRATEGY.md
 - lib/better_seo.rb
+- lib/better_seo/analytics/google_analytics.rb
+- lib/better_seo/analytics/google_tag_manager.rb
+- lib/better_seo/configuration.rb
+- lib/better_seo/dsl/base.rb
+- lib/better_seo/dsl/meta_tags.rb
+- lib/better_seo/dsl/open_graph.rb
+- lib/better_seo/dsl/twitter_cards.rb
+- lib/better_seo/errors.rb
+- lib/better_seo/generators/amp_generator.rb
+- lib/better_seo/generators/breadcrumbs_generator.rb
+- lib/better_seo/generators/canonical_url_manager.rb
+- lib/better_seo/generators/meta_tags_generator.rb
+- lib/better_seo/generators/open_graph_generator.rb
+- lib/better_seo/generators/robots_txt_generator.rb
+- lib/better_seo/generators/twitter_cards_generator.rb
+- lib/better_seo/image/optimizer.rb
+- lib/better_seo/rails/helpers/controller_helpers.rb
+- lib/better_seo/rails/helpers/seo_helper.rb
+- lib/better_seo/rails/helpers/structured_data_helper.rb
+- lib/better_seo/rails/model_helpers.rb
+- lib/better_seo/rails/railtie.rb
+- lib/better_seo/sitemap/builder.rb
+- lib/better_seo/sitemap/generator.rb
+- lib/better_seo/sitemap/sitemap_index.rb
+- lib/better_seo/sitemap/url_entry.rb
+- lib/better_seo/structured_data/article.rb
+- lib/better_seo/structured_data/base.rb
+- lib/better_seo/structured_data/breadcrumb_list.rb
+- lib/better_seo/structured_data/event.rb
+- lib/better_seo/structured_data/faq_page.rb
+- lib/better_seo/structured_data/generator.rb
+- lib/better_seo/structured_data/how_to.rb
+- lib/better_seo/structured_data/local_business.rb
+- lib/better_seo/structured_data/organization.rb
+- lib/better_seo/structured_data/person.rb
+- lib/better_seo/structured_data/product.rb
+- lib/better_seo/structured_data/recipe.rb
+- lib/better_seo/validators/seo_recommendations.rb
+- lib/better_seo/validators/seo_validator.rb
 - lib/better_seo/version.rb
+- lib/generators/better_seo/install_generator.rb
+- lib/generators/better_seo/templates/README
+- lib/generators/better_seo/templates/better_seo.rb
 - sig/better_seo.rbs
 homepage: https://github.com/alessiobussolari/better_seo
 licenses: