better_seo 0.1.0 → 0.5.0

data/README.md

@@ -1,38 +1,1175 @@
 # BetterSeo
 
-TODO: Delete this and the text below, and describe your gem
+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.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/better_seo`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Tests](https://img.shields.io/badge/tests-384%20passing-brightgreen)](https://github.com/yourusername/better_seo)
+[![Coverage](https://img.shields.io/badge/coverage-99.71%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.5.0)
+
+- **Core Configuration System**
+  - Singleton configuration with block-style setup
+  - Nested configuration objects
+  - Feature flags for enabling/disabling modules
+  - Validation with detailed error messages
+  - i18n support with multiple locales
+
+- **DSL Builders**
+  - **Meta Tags DSL**: title, description, keywords, author, canonical, robots, viewport, charset
+  - **Open Graph DSL**: Complete OG protocol support including articles, images, videos, audio
+  - **Twitter Cards DSL**: All card types (summary, summary_large_image, app, player)
+  - Fluent interface with method chaining
+  - Automatic validation (title/description length, required fields)
+
+- **HTML Generators**
+  - **MetaTagsGenerator**: Converts DSL to HTML meta tags
+  - **OpenGraphGenerator**: Converts DSL to Open Graph meta tags
+  - **TwitterCardsGenerator**: Converts DSL to Twitter Card meta tags
+  - HTML entity escaping for security
+  - Integration with DSL builders
+
+- **Rails Integration**
+  - **View Helpers**: `seo_meta_tags`, `seo_open_graph_tags`, `seo_twitter_tags`, `seo_tags`
+  - Support for hash configuration and DSL blocks
+  - Automatic HTML safety with `raw` helper
+  - Integration with global configuration defaults
+
+- **Sitemap Generation**
+  - **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)
+  - **Dynamic Generation**: Lambda support for dynamic attributes
+  - **File Writing**: Write sitemaps directly to files
+  - **Rails Integration**: Controller actions and Rake tasks
+  - **Validation**: Automatic URL validation (format, protocol)
+  - **Method Chaining**: Fluent interface for adding multiple URLs
+
+### 🚧 Planned
+
+- **Advanced Generators** (v0.6.0)
+  - Schema.org JSON-LD generator
+  - Breadcrumbs generator
+  - AMP HTML generator
+
+- **Advanced Rails Integration** (v0.6.0)
+  - Controller helpers for setting page SEO
+  - Railtie for automatic initialization
+  - Generator for initializer file
+
+- **Advanced Sitemap Features** (v0.6.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+)
+  - robots.txt generator
+  - Image optimization with WebP conversion
+  - Structured data builders (Organization, Person, Product, etc.)
+  - SEO validators and recommendations
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+### For Production Use (when published to RubyGems)
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'better_seo', '~> 0.5.0'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Or install it yourself as:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install better_seo
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### For Development (from source)
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'better_seo', git: 'https://github.com/alessiobussolari/better_seo.git', tag: 'v0.5.0'
+```
+
+Or clone and build locally:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+git clone https://github.com/alessiobussolari/better_seo.git
+cd better_seo
+gem build better_seo.gemspec
+gem install better_seo-0.5.0.gem
+```
+
+## Quick Start
+
+### 1. Configuration
+
+Create an initializer (Rails) or configure at app startup:
+
+```ruby
+# config/initializers/better_seo.rb
+BetterSeo.configure do |config|
+  config.site_name = "My Awesome Site"
+  config.default_locale = :en
+  config.available_locales = [:en, :it, :fr]
+
+  # Configure defaults for meta tags
+  config.meta_tags.default_title = "My Awesome Site"
+  config.meta_tags.title_separator = " | "
+  config.meta_tags.append_site_name = true
+  config.meta_tags.default_description = "The best site on the internet"
+  config.meta_tags.default_keywords = ["awesome", "site", "seo"]
+
+  # Configure Open Graph defaults
+  config.open_graph.site_name = "My Awesome Site"
+  config.open_graph.default_type = "website"
+  config.open_graph.default_locale = "en_US"
+
+  # Configure Twitter Cards defaults
+  config.twitter.site = "@mysite"
+  config.twitter.creator = "@myhandle"
+  config.twitter.card_type = "summary_large_image"
+end
+```
+
+### 2. Using DSL Builders
+
+#### Meta Tags
+
+```ruby
+meta = BetterSeo::DSL::MetaTags.new
+
+meta.evaluate do
+  title "My Page Title"
+  description "This is an amazing page about Ruby and SEO"
+  keywords "ruby", "seo", "meta tags"
+  author "John Doe"
+  canonical "https://example.com/my-page"
+  robots index: true, follow: true, noarchive: true
+  viewport # uses default: "width=device-width, initial-scale=1.0"
+  charset   # uses default: "UTF-8"
+end
+
+# Get the configuration
+config = meta.build
+# => {
+#   title: "My Page Title",
+#   description: "This is an amazing page...",
+#   keywords: ["ruby", "seo", "meta tags"],
+#   ...
+# }
+```
+
+#### Open Graph
+
+```ruby
+og = BetterSeo::DSL::OpenGraph.new
+
+og.evaluate do
+  title "My OG Title"
+  description "Description for social media"
+  type "article"
+  url "https://example.com/article"
+  image "https://example.com/image.jpg"
+  site_name "My Site"
+  locale "en_US"
+  locale_alternate "it_IT", "fr_FR"
+
+  # For article type
+  article do
+    author "John Doe"
+    published_time "2024-01-01T00:00:00Z"
+    modified_time "2024-01-02T00:00:00Z"
+    section "Technology"
+    tag "Ruby", "SEO", "OpenGraph"
+  end
+end
+
+config = og.build
+```
+
+#### Twitter Cards
+
+```ruby
+twitter = BetterSeo::DSL::TwitterCards.new
+
+twitter.evaluate do
+  card "summary_large_image"
+  site "@mysite"          # @ prefix added automatically
+  creator "myhandle"      # @ prefix added automatically
+  title "Twitter Card Title"
+  description "Description for Twitter"
+  image "https://example.com/twitter-image.jpg"
+  image_alt "Image description for accessibility"
+end
+
+config = twitter.build
+```
+
+#### Method Chaining
+
+All DSL builders support fluent interface:
+
+```ruby
+meta = BetterSeo::DSL::MetaTags.new
+  .title("Chained Title")
+  .description("Chained Description")
+  .keywords("ruby", "rails", "seo")
+  .author("Jane Doe")
+  .canonical("https://example.com/page")
+
+og = BetterSeo::DSL::OpenGraph.new
+  .title("OG Title")
+  .type("article")
+  .url("https://example.com")
+  .image("https://example.com/og.jpg")
+
+twitter = BetterSeo::DSL::TwitterCards.new
+  .card("summary_large_image")
+  .site("@mysite")
+  .title("Twitter Title")
+  .description("Twitter Description")
+  .image("https://example.com/twitter.jpg")
+```
+
+### 3. HTML Generation
+
+Once you've built your SEO configuration with DSL builders, use generators to convert them to HTML tags:
+
+#### Meta Tags Generator
+
+```ruby
+# Build configuration with DSL
+meta = BetterSeo::DSL::MetaTags.new
+meta.title("My Page Title")
+meta.description("Page description for SEO")
+meta.keywords("ruby", "seo", "rails")
+meta.canonical("https://example.com/page")
+meta.robots(index: true, follow: true)
+
+# Generate HTML tags
+generator = BetterSeo::Generators::MetaTagsGenerator.new(meta.build)
+html = generator.generate
+
+# Output:
+# <meta charset="UTF-8">
+# <meta name="viewport" content="width=device-width, initial-scale=1.0">
+# <title>My Page Title</title>
+# <meta name="description" content="Page description for SEO">
+# <meta name="keywords" content="ruby, seo, rails">
+# <link rel="canonical" href="https://example.com/page">
+# <meta name="robots" content="index, follow">
+```
+
+#### Open Graph Generator
+
+```ruby
+# Build configuration with DSL
+og = BetterSeo::DSL::OpenGraph.new
+og.title("Article Title")
+og.type("article")
+og.url("https://example.com/article")
+og.image(url: "https://example.com/og.jpg", width: 1200, height: 630)
+
+# Generate HTML tags
+generator = BetterSeo::Generators::OpenGraphGenerator.new(og.build)
+html = generator.generate
+
+# Output:
+# <meta property="og:title" content="Article Title">
+# <meta property="og:type" content="article">
+# <meta property="og:url" content="https://example.com/article">
+# <meta property="og:image" content="https://example.com/og.jpg">
+# <meta property="og:image:width" content="1200">
+# <meta property="og:image:height" content="630">
+```
+
+#### Twitter Cards Generator
+
+```ruby
+# Build configuration with DSL
+twitter = BetterSeo::DSL::TwitterCards.new
+twitter.card("summary_large_image")
+twitter.site("@mysite")
+twitter.title("Twitter Card Title")
+twitter.description("Description for Twitter")
+twitter.image("https://example.com/twitter.jpg")
+
+# Generate HTML tags
+generator = BetterSeo::Generators::TwitterCardsGenerator.new(twitter.build)
+html = generator.generate
+
+# Output:
+# <meta name="twitter:card" content="summary_large_image">
+# <meta name="twitter:site" content="@mysite">
+# <meta name="twitter:title" content="Twitter Card Title">
+# <meta name="twitter:description" content="Description for Twitter">
+# <meta name="twitter:image" content="https://example.com/twitter.jpg">
+```
+
+#### Complete Example
+
+```ruby
+# Build all SEO tags for a page
+meta = BetterSeo::DSL::MetaTags.new.evaluate do
+  title "My Awesome Page"
+  description "This page is about Ruby SEO"
+  keywords "ruby", "seo", "meta tags"
+end
+
+og = BetterSeo::DSL::OpenGraph.new.evaluate do
+  title "My Awesome Page"
+  type "article"
+  url "https://example.com/page"
+  image "https://example.com/og.jpg"
+end
+
+twitter = BetterSeo::DSL::TwitterCards.new.evaluate do
+  card "summary_large_image"
+  site "@mysite"
+  title "My Awesome Page"
+  image "https://example.com/twitter.jpg"
+end
+
+# Generate all HTML
+meta_html = BetterSeo::Generators::MetaTagsGenerator.new(meta.build).generate
+og_html = BetterSeo::Generators::OpenGraphGenerator.new(og.build).generate
+twitter_html = BetterSeo::Generators::TwitterCardsGenerator.new(twitter.build).generate
+
+# Combine and render in your view
+all_tags = [meta_html, og_html, twitter_html].join("\n")
+```
+
+#### Security Features
+
+All generators automatically escape HTML entities to prevent XSS attacks:
+
+```ruby
+meta = BetterSeo::DSL::MetaTags.new
+meta.title('Title with "quotes" & <script>alert("xss")</script>')
+
+generator = BetterSeo::Generators::MetaTagsGenerator.new(meta.build)
+html = generator.generate
+
+# Output:
+# <title>Title with &quot;quotes&quot; &amp; &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;</title>
+# All dangerous characters are properly escaped
+```
+
+### 4. Validation
+
+All DSL builders include automatic validation:
+
+```ruby
+meta = BetterSeo::DSL::MetaTags.new
+meta.title("A" * 80)  # Too long (max 60 chars recommended)
+meta.build
+# => BetterSeo::ValidationError: Title too long (80 chars, max 60 recommended)
+
+og = BetterSeo::DSL::OpenGraph.new
+og.title("Title")
+og.build
+# => BetterSeo::ValidationError: og:type is required, og:image is required, og:url is required
+
+twitter = BetterSeo::DSL::TwitterCards.new
+twitter.card("invalid_type")
+twitter.build
+# => BetterSeo::ValidationError: Invalid card type: invalid_type. Valid types: summary, summary_large_image, app, player
+```
+
+### 5. Rails Integration
+
+BetterSeo provides view helpers for easy integration in Rails applications.
+
+#### Setup
+
+Include the helpers in your `ApplicationHelper`:
+
+```ruby
+# app/helpers/application_helper.rb
+module ApplicationHelper
+  include BetterSeo::Rails::Helpers::SeoHelper
+end
+```
+
+Or include them globally in `ApplicationController`:
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  helper BetterSeo::Rails::Helpers::SeoHelper
+end
+```
+
+#### Using View Helpers
+
+##### Single Tag Group Helpers
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<head>
+  <%= seo_meta_tags do |meta|
+    meta.title "My Page Title"
+    meta.description "Page description"
+    meta.keywords "ruby", "rails", "seo"
+    meta.canonical request.original_url
+    meta.robots index: true, follow: true
+  end %>
+
+  <%= seo_open_graph_tags do |og|
+    og.title "My Page Title"
+    og.type "website"
+    og.url request.original_url
+    og.image image_url("og-image.jpg")
+    og.site_name "My Site"
+  end %>
+
+  <%= seo_twitter_tags do |twitter|
+    twitter.card "summary_large_image"
+    twitter.site "@mysite"
+    twitter.title "My Page Title"
+    twitter.description "Page description"
+    twitter.image image_url("twitter-image.jpg")
+  end %>
+</head>
+```
+
+##### All-in-One Helper
+
+```erb
+<%# Generate all SEO tags at once %>
+<head>
+  <%= seo_tags do |seo|
+    seo.meta do |meta|
+      meta.title @page_title || "Default Title"
+      meta.description @page_description
+      meta.keywords @page_keywords if @page_keywords
+      meta.canonical request.original_url
+    end
+
+    seo.og do |og|
+      og.title @page_title || "Default Title"
+      og.type "article"
+      og.url request.original_url
+      og.image @og_image || image_url("default-og.jpg")
+    end
+
+    seo.twitter do |twitter|
+      twitter.card "summary_large_image"
+      twitter.site "@mysite"
+      twitter.title @page_title || "Default Title"
+      twitter.image @twitter_image || image_url("default-twitter.jpg")
+    end
+  end %>
+</head>
+```
+
+#### Controller Integration
+
+Set SEO data in your controllers:
+
+```ruby
+class ArticlesController < ApplicationController
+  def show
+    @article = Article.find(params[:id])
+
+    # Set SEO variables for the view
+    @page_title = @article.title
+    @page_description = @article.excerpt
+    @page_keywords = @article.tags.pluck(:name)
+    @og_image = url_for(@article.cover_image) if @article.cover_image.attached?
+  end
+end
+```
+
+Then use them in your layout:
+
+```erb
+<head>
+  <%= seo_tags do |seo|
+    seo.meta do |meta|
+      meta.title @page_title if @page_title
+      meta.description @page_description if @page_description
+      meta.keywords(*@page_keywords) if @page_keywords
+      meta.canonical request.original_url
+    end
+
+    seo.og do |og|
+      og.title @page_title || "Default Title"
+      og.type "article"
+      og.url request.original_url
+      og.image @og_image if @og_image
+    end
+
+    seo.twitter do |twitter|
+      twitter.card "summary_large_image"
+      twitter.title @page_title || "Default Title"
+      twitter.description @page_description if @page_description
+    end
+  end %>
+</head>
+```
+
+#### Hash Configuration
+
+You can also pass hash configurations directly:
+
+```erb
+<%= seo_meta_tags(
+  title: "My Page",
+  description: "Description",
+  keywords: ["ruby", "rails"]
+) %>
+
+<%= seo_open_graph_tags(
+  title: "My Page",
+  type: "article",
+  url: request.original_url,
+  image: image_url("og.jpg")
+) %>
+
+<%= seo_twitter_tags(
+  card: "summary",
+  title: "My Page",
+  description: "Description"
+) %>
+```
+
+#### Partial Integration
+
+Create reusable SEO partials:
+
+```erb
+<%# app/views/shared/_seo.html.erb %>
+<%= seo_tags do |seo|
+  seo.meta do |meta|
+    meta.title local_assigns[:title] || "Default Title"
+    meta.description local_assigns[:description]
+    meta.canonical request.original_url
+  end
+
+  seo.og do |og|
+    og.title local_assigns[:title] || "Default Title"
+    og.type local_assigns[:og_type] || "website"
+    og.url request.original_url
+    og.image local_assigns[:og_image] || image_url("default-og.jpg")
+  end
+
+  seo.twitter do |twitter|
+    twitter.card "summary_large_image"
+    twitter.title local_assigns[:title] || "Default Title"
+  end
+end %>
+```
+
+Then use it in your views:
+
+```erb
+<%# app/views/articles/show.html.erb %>
+<%= render "shared/seo",
+    title: @article.title,
+    description: @article.excerpt,
+    og_type: "article",
+    og_image: url_for(@article.cover_image) %>
+```
+
+### 6. Sitemap Generation
+
+BetterSeo provides a comprehensive sitemap generation system with support for XML sitemaps, dynamic content, and model collections.
+
+#### Basic Sitemap Generation
+
+Generate a simple sitemap using the block syntax:
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  sitemap.add_url("https://example.com")
+  sitemap.add_url("https://example.com/about")
+  sitemap.add_url("https://example.com/contact")
+end
+
+puts xml
+# <?xml version="1.0" encoding="UTF-8"?>
+# <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+#   <url>
+#     <loc>https://example.com</loc>
+#     <changefreq>weekly</changefreq>
+#     <priority>0.5</priority>
+#   </url>
+#   ...
+# </urlset>
+```
+
+#### URL Entry with Full Attributes
+
+Add URLs with all sitemap attributes (lastmod, changefreq, priority):
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  sitemap.add_url(
+    "https://example.com",
+    lastmod: Date.today,
+    changefreq: "daily",
+    priority: 1.0
+  )
+
+  sitemap.add_url(
+    "https://example.com/blog",
+    lastmod: "2024-01-15",
+    changefreq: "weekly",
+    priority: 0.8
+  )
+
+  sitemap.add_url(
+    "https://example.com/about",
+    changefreq: "monthly",
+    priority: 0.5
+  )
+end
+```
+
+**Valid changefreq values**: `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`
+
+**Priority range**: 0.0 to 1.0 (default: 0.5)
+
+#### Method Chaining
+
+The builder supports fluent method chaining:
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  sitemap
+    .add_url("https://example.com", priority: 1.0)
+    .add_url("https://example.com/about", priority: 0.8)
+    .add_url("https://example.com/contact", priority: 0.6)
+end
+```
+
+#### Generate from Array
+
+Create a sitemap from an array of URLs:
+
+```ruby
+urls = [
+  "https://example.com",
+  "https://example.com/about",
+  "https://example.com/contact",
+  "https://example.com/blog"
+]
+
+xml = BetterSeo::Sitemap::Generator.generate_from(
+  urls,
+  changefreq: "weekly",
+  priority: 0.7
+)
+```
+
+#### Generate from Model Collection
+
+Generate sitemaps dynamically from your Rails models:
+
+```ruby
+# Simple example with Post model
+xml = BetterSeo::Sitemap::Generator.generate_from_collection(
+  Post.published,
+  url: ->(post) { "https://example.com/posts/#{post.slug}" },
+  lastmod: ->(post) { post.updated_at },
+  changefreq: "weekly",
+  priority: 0.8
+)
+```
+
+**Dynamic attributes with lambdas**:
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate_from_collection(
+  Article.all,
+  url: ->(article) { "https://example.com/articles/#{article.slug}" },
+  lastmod: ->(article) { article.updated_at },
+  changefreq: ->(article) do
+    article.featured? ? "daily" : "weekly"
+  end,
+  priority: ->(article) do
+    article.featured? ? 0.9 : 0.6
+  end
+)
+```
+
+#### Rails Routes Integration
+
+Generate sitemap from Rails routes:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Your routes...
+
+  # Sitemap endpoint
+  get '/sitemap.xml', to: 'sitemaps#index', defaults: { format: 'xml' }
+end
+
+# app/controllers/sitemaps_controller.rb
+class SitemapsController < ApplicationController
+  def index
+    @sitemap_xml = generate_sitemap
+    render xml: @sitemap_xml
+  end
+
+  private
+
+  def generate_sitemap
+    BetterSeo::Sitemap::Generator.generate do |sitemap|
+      # Static pages
+      sitemap.add_url(root_url, priority: 1.0, changefreq: "daily")
+      sitemap.add_url(about_url, priority: 0.8, changefreq: "monthly")
+      sitemap.add_url(contact_url, priority: 0.7, changefreq: "monthly")
+
+      # Dynamic content from models
+      Post.published.find_each do |post|
+        sitemap.add_url(
+          post_url(post),
+          lastmod: post.updated_at,
+          changefreq: "weekly",
+          priority: 0.8
+        )
+      end
+
+      Category.all.find_each do |category|
+        sitemap.add_url(
+          category_url(category),
+          lastmod: category.updated_at,
+          changefreq: "weekly",
+          priority: 0.7
+        )
+      end
+    end
+  end
+end
+```
+
+#### Write Sitemap to File
+
+Save sitemap directly to a file:
+
+```ruby
+# In a Rake task or script
+BetterSeo::Sitemap::Generator.write_to_file('public/sitemap.xml') do |sitemap|
+  sitemap.add_url("https://example.com", priority: 1.0)
+
+  Post.published.find_each do |post|
+    sitemap.add_url(
+      "https://example.com/posts/#{post.slug}",
+      lastmod: post.updated_at,
+      changefreq: "weekly",
+      priority: 0.8
+    )
+  end
+end
+
+# Returns the file path: "public/sitemap.xml"
+```
+
+#### Rake Task for Sitemap Generation
+
+Create a Rake task to regenerate your sitemap:
+
+```ruby
+# lib/tasks/sitemap.rake
+namespace :sitemap do
+  desc "Generate sitemap.xml"
+  task generate: :environment do
+    file_path = BetterSeo::Sitemap::Generator.write_to_file('public/sitemap.xml') do |sitemap|
+      # Add static pages
+      sitemap.add_url("#{ENV['SITE_URL']}", priority: 1.0, changefreq: "daily")
+      sitemap.add_url("#{ENV['SITE_URL']}/about", priority: 0.8)
+      sitemap.add_url("#{ENV['SITE_URL']}/contact", priority: 0.7)
+
+      # Add dynamic content
+      Post.published.find_each do |post|
+        sitemap.add_url(
+          "#{ENV['SITE_URL']}/posts/#{post.slug}",
+          lastmod: post.updated_at,
+          changefreq: "weekly",
+          priority: 0.8
+        )
+      end
+    end
+
+    puts "Sitemap generated at #{file_path}"
+  end
+end
+
+# Run with: rake sitemap:generate
+```
+
+#### Using the Builder Directly
+
+For more control, use the Builder class directly:
+
+```ruby
+builder = BetterSeo::Sitemap::Builder.new
+
+# Add URLs
+builder.add_url("https://example.com", priority: 1.0)
+builder.add_url("https://example.com/about", priority: 0.8)
+
+# Add multiple URLs at once
+builder.add_urls(
+  ["https://example.com/blog", "https://example.com/contact"],
+  changefreq: "weekly",
+  priority: 0.7
+)
+
+# Remove a URL
+builder.remove_url("https://example.com/contact")
+
+# Check size
+puts builder.size # => 3
+
+# Iterate over URLs
+builder.each do |url|
+  puts "#{url.loc} - Priority: #{url.priority}"
+end
+
+# Generate XML
+xml = builder.to_xml
+
+# Validate all URLs
+builder.validate! # Raises ValidationError if any URL is invalid
+
+# Clear all URLs
+builder.clear
 ```
 
-## Usage
+#### URL Entry Details
 
-TODO: Write usage instructions here
+Work with individual URL entries:
+
+```ruby
+entry = BetterSeo::Sitemap::UrlEntry.new(
+  "https://example.com/page",
+  lastmod: Date.today,
+  changefreq: "daily",
+  priority: 0.8
+)
+
+# Access attributes
+entry.loc         # => "https://example.com/page"
+entry.lastmod     # => "2024-01-15"
+entry.changefreq  # => "daily"
+entry.priority    # => 0.8
+
+# Update attributes
+entry.lastmod = Date.new(2024, 1, 20)
+entry.changefreq = "weekly"
+entry.priority = 0.9
+
+# Generate XML for single entry
+entry.to_xml
+# <url>
+#   <loc>https://example.com/page</loc>
+#   <lastmod>2024-01-20</lastmod>
+#   <changefreq>weekly</changefreq>
+#   <priority>0.9</priority>
+# </url>
+
+# Convert to hash
+entry.to_h
+# {
+#   loc: "https://example.com/page",
+#   lastmod: "2024-01-20",
+#   changefreq: "weekly",
+#   priority: 0.9
+# }
+
+# Validate
+entry.validate! # Raises ValidationError if invalid
+```
+
+#### Advanced: Multi-Model Sitemap
+
+Combine multiple models in a single sitemap:
+
+```ruby
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  # Homepage
+  sitemap.add_url("https://example.com", priority: 1.0, changefreq: "daily")
+
+  # Blog posts
+  Post.published.find_each do |post|
+    sitemap.add_url(
+      "https://example.com/posts/#{post.slug}",
+      lastmod: post.updated_at,
+      changefreq: post.featured? ? "daily" : "weekly",
+      priority: post.featured? ? 0.9 : 0.7
+    )
+  end
+
+  # Categories
+  Category.all.find_each do |category|
+    sitemap.add_url(
+      "https://example.com/categories/#{category.slug}",
+      lastmod: category.updated_at,
+      changefreq: "weekly",
+      priority: 0.6
+    )
+  end
+
+  # Static pages
+  %w[about contact privacy terms].each do |page|
+    sitemap.add_url(
+      "https://example.com/#{page}",
+      changefreq: "monthly",
+      priority: 0.5
+    )
+  end
+end
+```
+
+#### Validation
+
+All URLs are automatically validated when generating:
+
+```ruby
+# This will raise BetterSeo::ValidationError
+xml = BetterSeo::Sitemap::Generator.generate do |sitemap|
+  sitemap.add_url("")  # Error: Location is required
+  sitemap.add_url("not-a-valid-url")  # Error: Invalid URL format
+  sitemap.add_url("ftp://example.com")  # Error: Must be HTTP/HTTPS
+end
+
+# Validate manually
+builder = BetterSeo::Sitemap::Builder.new
+builder.add_url("https://example.com")
+builder.validate!  # Returns true if all URLs valid
+```
+
+#### Complete Example: Production Sitemap
+
+```ruby
+# app/services/sitemap_generator_service.rb
+class SitemapGeneratorService
+  def self.generate
+    BetterSeo::Sitemap::Generator.write_to_file(Rails.root.join('public', 'sitemap.xml')) do |sitemap|
+      add_static_pages(sitemap)
+      add_blog_posts(sitemap)
+      add_categories(sitemap)
+      add_products(sitemap) if defined?(Product)
+    end
+  end
+
+  private_class_method def self.add_static_pages(sitemap)
+    sitemap.add_url(Rails.application.routes.url_helpers.root_url, priority: 1.0, changefreq: "daily")
+    sitemap.add_url(Rails.application.routes.url_helpers.about_url, priority: 0.8, changefreq: "monthly")
+    sitemap.add_url(Rails.application.routes.url_helpers.contact_url, priority: 0.7, changefreq: "monthly")
+  end
+
+  private_class_method def self.add_blog_posts(sitemap)
+    Post.published.find_each do |post|
+      sitemap.add_url(
+        Rails.application.routes.url_helpers.post_url(post),
+        lastmod: post.updated_at,
+        changefreq: post.frequently_updated? ? "daily" : "weekly",
+        priority: calculate_post_priority(post)
+      )
+    end
+  end
+
+  private_class_method def self.add_categories(sitemap)
+    Category.all.find_each do |category|
+      sitemap.add_url(
+        Rails.application.routes.url_helpers.category_url(category),
+        lastmod: category.posts.maximum(:updated_at),
+        changefreq: "weekly",
+        priority: 0.6
+      )
+    end
+  end
+
+  private_class_method def self.add_products(sitemap)
+    Product.available.find_each do |product|
+      sitemap.add_url(
+        Rails.application.routes.url_helpers.product_url(product),
+        lastmod: product.updated_at,
+        changefreq: "daily",
+        priority: product.featured? ? 0.95 : 0.75
+      )
+    end
+  end
+
+  private_class_method def self.calculate_post_priority(post)
+    base_priority = 0.7
+    base_priority += 0.2 if post.featured?
+    base_priority += 0.1 if post.comments_count > 10
+    [base_priority, 1.0].min
+  end
+end
+
+# Call from rake task or controller:
+# SitemapGeneratorService.generate
+```
+
+## Configuration Reference
+
+### Global Configuration
+
+```ruby
+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"
+  config.meta_tags.default_keywords = ["keyword1", "keyword2"]
+  config.meta_tags.default_author = "Your Name"
+
+  # 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.jpg"
+  config.open_graph.default_image.width = 1200
+  config.open_graph.default_image.height = 630
+
+  # Twitter Cards configuration
+  config.twitter.enabled = true
+  config.twitter.site = "@mysite"
+  config.twitter.creator = "@myhandle"
+  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"
+  }
+
+  # Sitemap configuration (planned)
+  config.sitemap.enabled = false
+  config.sitemap.host = "https://example.com"
+  config.sitemap.output_path = "public/sitemap.xml"
+
+  # Robots.txt configuration (planned)
+  config.robots.enabled = false
+  config.robots.output_path = "public/robots.txt"
+
+  # Image optimization configuration (planned)
+  config.images.enabled = false
+  config.images.webp.enabled = true
+  config.images.webp.quality = 80
+end
+```
+
+### Checking Configuration
+
+```ruby
+# Access configuration
+BetterSeo.configuration.site_name
+# => "My Site"
+
+# Check if features are enabled
+BetterSeo.enabled?(:open_graph)
+# => true
+
+BetterSeo.enabled?(:sitemap)
+# => false
+
+# Reset configuration (useful for testing)
+BetterSeo.reset_configuration!
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run tests with coverage
+bundle exec rspec --format documentation
+
+# Check code coverage
+open coverage/index.html
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Running Tests
+
+The gem uses RSpec with SimpleCov for test coverage. We maintain **100% code coverage**.
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/dsl/meta_tags_spec.rb
+
+# Run with documentation format
+bundle exec rspec --format documentation
+```
+
+Current test statistics:
+- **286 tests** passing
+- **100% code coverage** (562/562 lines)
+- **3 DSL builders** fully tested
+- **3 HTML generators** fully tested
+- **1 Rails view helper module** fully tested
+- **1 core configuration system** fully tested
+
+## Architecture
+
+```
+lib/better_seo/
+├── version.rb                          # Gem version
+├── errors.rb                           # Custom error classes
+├── configuration.rb                    # Main configuration class
+├── dsl/
+│   ├── base.rb                        # Base DSL builder class
+│   ├── meta_tags.rb                   # Meta tags DSL
+│   ├── open_graph.rb                  # Open Graph DSL
+│   └── twitter_cards.rb               # Twitter Cards DSL
+├── generators/
+│   ├── meta_tags_generator.rb         # HTML meta tags generator
+│   ├── open_graph_generator.rb        # Open Graph tags generator
+│   └── twitter_cards_generator.rb     # Twitter Cards generator
+├── rails/
+│   └── helpers/
+│       └── seo_helper.rb              # Rails view helpers
+└── (planned)
+    ├── validators/                    # SEO validators
+    └── sitemap/                       # Sitemap generation
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/better_seo. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/better_seo/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/better_seo.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Write tests (we maintain 100% coverage)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin feature/my-new-feature`)
+6. Create new Pull Request
 
 ## License
 
@@ -40,4 +1177,18 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the BetterSeo project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/better_seo/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the BetterSeo project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yourusername/better_seo/blob/main/CODE_OF_CONDUCT.md).
+
+## Roadmap
+
+See [docs/00_OVERVIEW.md](docs/00_OVERVIEW.md) for the complete implementation roadmap.
+
+### Version History
+
+- **v0.1.0** - Core configuration system
+- **v0.2.0** - DSL builders (Meta Tags, Open Graph, Twitter Cards)
+- **v0.3.0** - HTML generators (Meta Tags, Open Graph, Twitter Cards)
+- **v0.4.0** - Rails view helpers integration ← **Current**
+- **v0.5.0** - Sitemap generation (planned)
+- **v0.6.0** - Advanced features (planned)
+- **v1.0.0** - Stable release (planned)