better_seo 0.14.0 → 1.0.0.2

data/docs/02_META_TAGS_AND_OPEN_GRAPH.md

@@ -0,0 +1,251 @@
+# Step 02: Meta Tags e Open Graph
+
+**Versione Target**: 0.3.0
+**Durata Stimata**: 2-3 settimane
+**Priorità**: 🔴 CRITICA (Essential SEO)
+**Dipendenze**: Step 01 completato
+
+---
+
+## Obiettivi dello Step
+
+Implementare funzionalità SEO essenziali:
+
+1. ✅ Meta tags HTML (title, description, keywords, robots, canonical)
+2. ✅ Open Graph protocol completo
+3. ✅ Twitter Cards
+4. ✅ Validatori meta tags
+5. ✅ HTML generators
+6. ✅ Rails helpers base
+
+---
+
+## File da Creare
+
+```
+lib/better_seo/dsl/meta_tags.rb
+lib/better_seo/dsl/open_graph.rb
+lib/better_seo/dsl/twitter_cards.rb
+lib/better_seo/generators/meta_tags_generator.rb
+lib/better_seo/generators/open_graph_generator.rb
+lib/better_seo/generators/twitter_cards_generator.rb
+lib/better_seo/validators/meta_validator.rb
+lib/better_seo/rails/helpers/meta_tags_helper.rb (partial)
+lib/better_seo/rails/helpers/open_graph_helper.rb (partial)
+```
+
+---
+
+## Implementazione: DSL Meta Tags
+
+```ruby
+# lib/better_seo/dsl/meta_tags.rb
+module BetterSeo
+  module DSL
+    class MetaTags < Base
+      def title(value = nil)
+        value ? set(:title, value) : get(:title)
+      end
+
+      def description(value = nil)
+        value ? set(:description, value) : get(:description)
+      end
+
+      def keywords(*values)
+        values.any? ? set(:keywords, values.flatten) : get(:keywords)
+      end
+
+      def author(value = nil)
+        value ? set(:author, value) : get(:author)
+      end
+
+      def canonical(value = nil)
+        value ? set(:canonical, value) : get(:canonical)
+      end
+
+      def robots(index: true, follow: true, **options)
+        set(:robots, { index: index, follow: follow }.merge(options))
+      end
+
+      def viewport(value = "width=device-width, initial-scale=1.0")
+        set(:viewport, value)
+      end
+
+      def charset(value = "UTF-8")
+        set(:charset, value)
+      end
+
+      protected
+
+      def validate!
+        errors = []
+
+        if config[:title] && config[:title].length > 60
+          errors << "Title too long (#{config[:title].length} chars, max 60 recommended)"
+        end
+
+        if config[:description] && config[:description].length > 160
+          errors << "Description too long (#{config[:description].length} chars, max 160 recommended)"
+        end
+
+        raise ValidationError, errors.join(", ") if errors.any?
+      end
+    end
+  end
+end
+```
+
+---
+
+## Implementazione: Generator Meta Tags
+
+```ruby
+# lib/better_seo/generators/meta_tags_generator.rb
+module BetterSeo
+  module Generators
+    class MetaTagsGenerator
+      def initialize(config)
+        @config = config
+      end
+
+      def generate
+        tags = []
+
+        tags << charset_tag if @config[:charset]
+        tags << viewport_tag if @config[:viewport]
+        tags << title_tag if @config[:title]
+        tags << description_tag if @config[:description]
+        tags << keywords_tag if @config[:keywords]&.any?
+        tags << author_tag if @config[:author]
+        tags << robots_tag if @config[:robots]
+        tags << canonical_tag if @config[:canonical]
+
+        tags.compact.join("\n")
+      end
+
+      private
+
+      def charset_tag
+        %(<meta charset="#{escape(@config[:charset])}">)
+      end
+
+      def viewport_tag
+        %(<meta name="viewport" content="#{escape(@config[:viewport])}">)
+      end
+
+      def title_tag
+        %(<title>#{escape(@config[:title])}</title>)
+      end
+
+      def description_tag
+        %(<meta name="description" content="#{escape(@config[:description])}">)
+      end
+
+      def keywords_tag
+        keywords = Array(@config[:keywords]).join(", ")
+        %(<meta name="keywords" content="#{escape(keywords)}">)
+      end
+
+      def author_tag
+        %(<meta name="author" content="#{escape(@config[:author])}">)
+      end
+
+      def robots_tag
+        robots = @config[:robots]
+        parts = []
+        parts << "index" if robots[:index]
+        parts << "noindex" unless robots[:index]
+        parts << "follow" if robots[:follow]
+        parts << "nofollow" unless robots[:follow]
+
+        %(<meta name="robots" content="#{parts.join(", ")}">)
+      end
+
+      def canonical_tag
+        %(<link rel="canonical" href="#{escape(@config[:canonical])}">)
+      end
+
+      def escape(text)
+        text.to_s.gsub('"', '&quot;').gsub('<', '&lt;').gsub('>', '&gt;')
+      end
+    end
+  end
+end
+```
+
+---
+
+## Test Suite
+
+```ruby
+# spec/dsl/meta_tags_spec.rb
+RSpec.describe BetterSeo::DSL::MetaTags do
+  subject(:meta) { described_class.new }
+
+  it "sets title" do
+    meta.title "My Page Title"
+    expect(meta.title).to eq("My Page Title")
+  end
+
+  it "validates title length" do
+    meta.title "A" * 80
+    expect { meta.build }.to raise_error(BetterSeo::ValidationError, /too long/)
+  end
+
+  it "sets robots directives" do
+    meta.robots index: true, follow: false
+    expect(meta.robots).to eq({ index: true, follow: false })
+  end
+end
+
+# spec/generators/meta_tags_generator_spec.rb
+RSpec.describe BetterSeo::Generators::MetaTagsGenerator do
+  let(:config) do
+    {
+      charset: "UTF-8",
+      title: "Test Page",
+      description: "Test description",
+      canonical: "https://example.com/test"
+    }
+  end
+
+  subject(:generator) { described_class.new(config) }
+
+  describe "#generate" do
+    it "generates HTML meta tags" do
+      html = generator.generate
+
+      expect(html).to include('<meta charset="UTF-8">')
+      expect(html).to include('<title>Test Page</title>')
+      expect(html).to include('name="description"')
+      expect(html).to include('rel="canonical"')
+    end
+
+    it "escapes HTML entities" do
+      config[:title] = 'Test <script>alert("xss")</script>'
+      html = generator.generate
+
+      expect(html).to include('&lt;script&gt;')
+      expect(html).not_to include('<script>')
+    end
+  end
+end
+```
+
+---
+
+## Checklist Completamento
+
+- [ ] DSL MetaTags implementato e testato
+- [ ] DSL OpenGraph implementato e testato
+- [ ] DSL TwitterCards implementato e testato
+- [ ] Generator MetaTags con HTML output
+- [ ] Generator OpenGraph con property tags
+- [ ] Generator TwitterCards
+- [ ] Validatori per lunghezze ottimali
+- [ ] Test coverage > 90%
+- [ ] Integration con Step 01 Configuration
+
+---
+
+**Prossimi Passi**: Step 03 - Structured Data

data/docs/03_STRUCTURED_DATA.md

@@ -0,0 +1,140 @@
+# Step 03: Structured Data (JSON-LD)
+
+**Versione Target**: 0.4.0
+**Durata Stimata**: 2-3 settimane
+**Priorità**: 🟡 MEDIA
+**Dipendenze**: Step 01
+
+---
+
+## Obiettivi
+
+1. ✅ Schema.org types (Article, Product, Organization, Person, Breadcrumb)
+2. ✅ JSON-LD generator
+3. ✅ DSL per structured data
+4. ✅ Schema validator
+5. ✅ Multiple structured data per page
+
+---
+
+## File da Creare
+
+```
+lib/better_seo/schema/base.rb
+lib/better_seo/schema/article.rb
+lib/better_seo/schema/product.rb
+lib/better_seo/schema/organization.rb
+lib/better_seo/schema/person.rb
+lib/better_seo/schema/breadcrumb.rb
+lib/better_seo/generators/json_ld_generator.rb
+lib/better_seo/dsl/structured_data.rb
+lib/better_seo/validators/schema_validator.rb
+```
+
+---
+
+## Implementazione: Schema Article
+
+```ruby
+# lib/better_seo/schema/article.rb
+module BetterSeo
+  module Schema
+    class Article < Base
+      def schema_type
+        "Article"
+      end
+
+      def headline(value = nil)
+        value ? set(:headline, value) : get(:headline)
+      end
+
+      def date_published(value = nil)
+        value ? set(:datePublished, format_date(value)) : get(:datePublished)
+      end
+
+      def date_modified(value = nil)
+        value ? set(:dateModified, format_date(value)) : get(:dateModified)
+      end
+
+      def author(&block)
+        if block_given?
+          person = Person.new
+          person.evaluate(&block)
+          set(:author, person.to_schema)
+        else
+          get(:author)
+        end
+      end
+
+      def publisher(&block)
+        if block_given?
+          org = Organization.new
+          org.evaluate(&block)
+          set(:publisher, org.to_schema)
+        else
+          get(:publisher)
+        end
+      end
+
+      def to_schema
+        {
+          "@context" => "https://schema.org",
+          "@type" => schema_type
+        }.merge(config)
+      end
+
+      private
+
+      def format_date(value)
+        return value if value.is_a?(String)
+        value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+      end
+    end
+  end
+end
+```
+
+---
+
+## Implementazione: JSON-LD Generator
+
+```ruby
+# lib/better_seo/generators/json_ld_generator.rb
+require "json"
+
+module BetterSeo
+  module Generators
+    class JsonLdGenerator
+      def initialize(schema_data)
+        @schema_data = Array(schema_data)
+      end
+
+      def generate
+        return "" if @schema_data.empty?
+
+        scripts = @schema_data.map do |schema|
+          json = JSON.pretty_generate(schema)
+          %(<script type="application/ld+json">\n#{json}\n</script>)
+        end
+
+        scripts.join("\n")
+      end
+    end
+  end
+end
+```
+
+---
+
+## Checklist
+
+- [ ] Schema base types (Article, Product, Organization, Person, Breadcrumb)
+- [ ] JSON-LD generator
+- [ ] DSL structured_data
+- [ ] Schema validator (schema.org compliance)
+- [ ] Support multiple schemas per page
+- [ ] Test coverage > 90%
+
+---
+
+**Prossimi Passi**: Step 04 - Sitemap & Robots

data/docs/04_SITEMAP_AND_ROBOTS.md

@@ -0,0 +1,131 @@
+# Step 04: Sitemap XML e Robots.txt
+
+**Versione Target**: 0.5.0
+**Durata Stimata**: 1-2 settimane
+**Priorità**: 🟡 MEDIA
+**Dipendenze**: Step 01
+
+---
+
+## Obiettivi
+
+1. ✅ Sitemap XML generator
+2. ✅ Dynamic sitemap from Rails models
+3. ✅ Sitemap index (>50k URLs)
+4. ✅ Robots.txt generator
+5. ✅ Ping search engines
+6. ✅ Rake tasks
+
+---
+
+## File da Creare
+
+```
+lib/better_seo/generators/sitemap_generator.rb
+lib/better_seo/generators/robots_generator.rb
+lib/better_seo/tasks/sitemap.rake
+lib/better_seo/tasks/robots.rake
+lib/better_seo/sitemap/url_builder.rb
+lib/better_seo/sitemap/index_builder.rb
+```
+
+---
+
+## Implementazione: Sitemap Generator
+
+```ruby
+# lib/better_seo/generators/sitemap_generator.rb
+require "builder"
+
+module BetterSeo
+  module Generators
+    class SitemapGenerator
+      def initialize(urls, options = {})
+        @urls = urls
+        @options = options
+      end
+
+      def generate
+        xml = Builder::XmlMarkup.new(indent: 2)
+        xml.instruct! :xml, version: "1.0", encoding: "UTF-8"
+
+        xml.urlset xmlns: "http://www.sitemaps.org/schemas/sitemap/0.9" do
+          @urls.each do |url_data|
+            xml.url do
+              xml.loc url_data[:loc]
+              xml.lastmod url_data[:lastmod] if url_data[:lastmod]
+              xml.changefreq url_data[:changefreq] if url_data[:changefreq]
+              xml.priority url_data[:priority] if url_data[:priority]
+            end
+          end
+        end
+
+        xml.target!
+      end
+
+      def save(path)
+        File.write(path, generate)
+      end
+    end
+  end
+end
+```
+
+---
+
+## Rake Tasks
+
+```ruby
+# lib/better_seo/tasks/sitemap.rake
+namespace :better_seo do
+  namespace :sitemap do
+    desc "Generate sitemap.xml"
+    task generate: :environment do
+      config = BetterSeo.configuration.sitemap
+
+      urls = []
+
+      # Add static URLs
+      urls << { loc: "#{config.host}/", priority: 1.0, changefreq: "daily" }
+
+      # Add dynamic URLs from models (configured in better_seo.yml)
+      # Article.published.each do |article|
+      #   urls << {
+      #     loc: "#{config.host}#{article_path(article)}",
+      #     lastmod: article.updated_at.iso8601,
+      #     changefreq: "weekly",
+      #     priority: 0.8
+      #   }
+      # end
+
+      generator = BetterSeo::Generators::SitemapGenerator.new(urls)
+      generator.save(config.output_path)
+
+      puts "✓ Sitemap generated: #{config.output_path}"
+    end
+
+    desc "Generate and ping search engines"
+    task generate_and_ping: :generate do
+      # Ping Google, Bing, etc.
+      puts "✓ Pinged search engines"
+    end
+  end
+end
+```
+
+---
+
+## Checklist
+
+- [ ] Sitemap XML generator con Builder
+- [ ] Dynamic URLs from models
+- [ ] Sitemap index per >50k URLs
+- [ ] Robots.txt generator
+- [ ] Rake tasks (generate, ping)
+- [ ] Gzip compression opzionale
+- [ ] Image sitemap support
+- [ ] Test coverage > 85%
+
+---
+
+**Prossimi Passi**: Step 05 - Rails Integration

data/docs/05_RAILS_INTEGRATION.md

@@ -0,0 +1,175 @@
+# Step 05: Rails Integration Completa
+
+**Versione Target**: 0.6.0
+**Durata Stimata**: 2 settimane
+**Priorità**: 🔴 ALTA
+**Dipendenze**: Step 01, 02, 03, 04
+
+---
+
+## Obiettivi
+
+1. ✅ View helpers completi (meta_tags, open_graph, structured_data)
+2. ✅ Controller concerns (SeoAware)
+3. ✅ Rails generators (install, config, sitemap, robots)
+4. ✅ Rails Engine
+5. ✅ Routes integration
+6. ✅ Middleware (optional)
+
+---
+
+## File da Creare
+
+```
+lib/better_seo/rails/helpers/meta_tags_helper.rb
+lib/better_seo/rails/helpers/open_graph_helper.rb
+lib/better_seo/rails/helpers/structured_data_helper.rb
+lib/better_seo/rails/concerns/seo_aware.rb
+lib/better_seo/rails/engine.rb
+lib/generators/better_seo/install_generator.rb
+lib/generators/better_seo/config_generator.rb
+lib/generators/better_seo/page_generator.rb (parziale, completato in Step 06)
+```
+
+---
+
+## Implementazione: MetaTagsHelper
+
+```ruby
+# lib/better_seo/rails/helpers/meta_tags_helper.rb
+module BetterSeo
+  module Rails
+    module Helpers
+      module MetaTagsHelper
+        def seo_meta_tags(options = {}, &block)
+          meta_dsl = BetterSeo::DSL::MetaTags.new
+
+          # Load defaults from configuration
+          config = BetterSeo.configuration.meta_tags
+          meta_dsl.merge!(config.to_h)
+
+          # Load from controller if set
+          if controller.respond_to?(:current_seo_meta) && controller.current_seo_meta
+            meta_dsl.merge!(controller.current_seo_meta)
+          end
+
+          # Apply block overrides
+          meta_dsl.evaluate(&block) if block_given?
+
+          # Apply options hash
+          meta_dsl.merge!(options) if options.any?
+
+          # Generate HTML
+          generator = BetterSeo::Generators::MetaTagsGenerator.new(meta_dsl.build)
+          generator.generate.html_safe
+        end
+
+        def render_seo_tags
+          tags = []
+          tags << seo_meta_tags
+          tags << open_graph_tags if BetterSeo.configuration.open_graph_enabled?
+          tags << twitter_card_tags if BetterSeo.configuration.twitter_enabled?
+          tags << structured_data_tags if BetterSeo.configuration.structured_data_enabled?
+
+          safe_join(tags, "\n")
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## Implementazione: SeoAware Concern
+
+```ruby
+# lib/better_seo/rails/concerns/seo_aware.rb
+module BetterSeo
+  module Rails
+    module Concerns
+      module SeoAware
+        extend ActiveSupport::Concern
+
+        included do
+          helper_method :current_seo_meta, :current_seo_og, :current_seo_structured_data
+        end
+
+        def set_seo(&block)
+          @_seo_builder = BetterSeo::DSL::MetaTags.new
+          @_seo_builder.evaluate(&block) if block_given?
+        end
+
+        def set_seo_from_locale(page_name)
+          # Implementato in Step 06
+        end
+
+        def current_seo_meta
+          @_seo_builder&.to_h || {}
+        end
+
+        def current_seo_og
+          @_seo_og || {}
+        end
+
+        def current_seo_structured_data
+          @_seo_structured_data || []
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## Rails Generator: Install
+
+```ruby
+# lib/generators/better_seo/install_generator.rb
+module BetterSeo
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install BetterSeo in your Rails application"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/better_seo.rb"
+      end
+
+      def create_config
+        template "better_seo.yml", "config/better_seo.yml"
+      end
+
+      def create_locale_directories
+        empty_directory "config/locales/seo/it"
+        empty_directory "config/locales/seo/en"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end
+```
+
+---
+
+## Checklist
+
+- [ ] View helpers (meta_tags, open_graph, structured_data)
+- [ ] Helper `render_seo_tags` (all-in-one)
+- [ ] Controller concern `SeoAware`
+- [ ] Method `set_seo` DSL in controllers
+- [ ] Rails generators (install, config)
+- [ ] Generator templates
+- [ ] Rails Engine per routes
+- [ ] Auto-include helpers in ApplicationHelper
+- [ ] Auto-include concerns in ApplicationController
+- [ ] Test coverage > 90%
+
+---
+
+**Prossimi Passi**: Step 06 - i18n Page Generator