better_seo 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9636cfad8403d7c6f0433fd5a0434b0fb46b4a51a4e1076ed6a348f81185b1f
-  data.tar.gz: 9a7fa5ea86498ef3c77ee6adb69c40ccd63739879fe7574cbaef70503c87bb3d
+  metadata.gz: 21564a3e273f4c6274fcafaddc9dc0b9e5e36524c1ca2a548ae48e455490034f
+  data.tar.gz: d82e2faf6d565f8be930ca24e9c3af7b60de23c8ed02dbcc0d14390c6725580b
 SHA512:
-  metadata.gz: 364c805e5bf4da2d5b738727a8786b44f62ea621396d3b307985b54e0141f9f4c48ff58c1d9964b2df972976f78312893d1d603bd7e5e01f06c57340c3e59d71
-  data.tar.gz: fe9f49347a0ce696876b1e946151a77fa2a8b1f637a24b2bcbdf9f88437e94c9a59af1850161d9a43883867634b44540f866efb624fc282b39c28a2ea27806f8
+  metadata.gz: 656e243f281d61d4afac21dfdd2f18be27659ae695bc5d6770146fc7e234135a21e221847157d75bb50b1d41d2798094e87868fc8d91cac1eee0fe38e651c6eb
+  data.tar.gz: b65f741d51b2b192c2456356081ad908145d68f93d37e64c6ba5d45c3ae838820120d7c852592dd60d1f3da54e2bf21e88316bede5c2e9971d0af24d2cecbe50

data/CHANGELOG.md

@@ -1,5 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
-## [0.1.0] - 2025-10-05
+## [0.4.0] - 2025-01-23
+
+### Added
+- Rails view helpers for easy integration
+  - `seo_meta_tags` - Generate HTML meta tags
+  - `seo_open_graph_tags` - Generate Open Graph tags
+  - `seo_twitter_tags` - Generate Twitter Card tags
+  - `seo_tags` - Generate all SEO tags at once
+- Support for both hash configuration and DSL blocks in helpers
+- Automatic HTML safety with `raw` helper
+- Controller integration patterns and examples
+- Complete Rails integration documentation
+
+### Test Coverage
+- 286 tests passing
+- 100% code coverage (562/562 lines)
+
+## [0.3.0] - 2025-01-23
+
+### Added
+- HTML Generators for converting DSL to HTML tags
+  - `MetaTagsGenerator` - Converts meta tags DSL to HTML
+  - `OpenGraphGenerator` - Converts Open Graph DSL to HTML
+  - `TwitterCardsGenerator` - Converts Twitter Cards DSL to HTML
+- HTML entity escaping for security (XSS prevention)
+
+### Test Coverage
+- 271 tests passing
+- 100% code coverage (505/505 lines)
+
+## [0.2.0] - 2025-01-22
+
+### Added
+- DSL Builders for creating SEO configurations
+  - `DSL::MetaTags` - For HTML meta tags
+  - `DSL::OpenGraph` - For Open Graph protocol
+  - `DSL::TwitterCards` - For Twitter Cards
+- Fluent interface with method chaining
+- Automatic validation for all DSL builders
+
+### Test Coverage
+- 175 tests passing
+- 100% code coverage (327/327 lines)
+
+## [0.1.0] - 2025-01-22
+
+### Added
+- Core configuration system with singleton pattern
+- Nested configuration objects
+- Feature flags for enabling/disabling modules
+- Validation with detailed error messages
+- i18n support with multiple locales
+- Custom error classes
 
-- Initial release
+### Test Coverage
+- 74 tests passing
+- 100% code coverage (179/179 lines)

data/README.md

@@ -1,38 +1,710 @@
 # 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-286%20passing-brightgreen)](https://github.com/yourusername/better_seo)
+[![Coverage](https://img.shields.io/badge/coverage-100%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.2.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
+
+### 🚧 Planned
+
+- **Advanced Generators** (v0.5.0)
+  - Schema.org JSON-LD generator
+  - Breadcrumbs generator
+  - AMP HTML generator
+
+- **Advanced Rails Integration** (v0.5.0)
+  - Controller helpers for setting page SEO
+  - Railtie for automatic initialization
+  - Generator for initializer file
+
+- **Sitemap Generation** (v0.5.0)
+  - XML sitemap builder
+  - Automatic Rails routes integration
+  - Multi-language sitemap support
+  - Sitemap index for large sites
+
+- **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.
+Add this line to your application's Gemfile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem 'better_seo'
+```
+
+And then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it yourself as:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install better_seo
+```
+
+## 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
 ```
 
-## Usage
+Or include them globally in `ApplicationController`:
 
-TODO: Write usage instructions here
+```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) %>
+```
+
+## 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
+```
+
+### 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
 
-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).
+```
+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 +712,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)

data/lib/better_seo/version.rb

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

data/lib/better_seo.rb

@@ -1,8 +1,44 @@
 # frozen_string_literal: true
 
+require "active_support"
+require "active_support/core_ext"
+
 require_relative "better_seo/version"
+require_relative "better_seo/errors"
+require_relative "better_seo/configuration"
+require_relative "better_seo/dsl/base"
+require_relative "better_seo/dsl/meta_tags"
+require_relative "better_seo/dsl/open_graph"
+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/rails/helpers/seo_helper"
 
 module BetterSeo
-  class Error < StandardError; end
-  # Your code goes here...
+  class << self
+    # Accesso alla configurazione singleton
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Block-style configuration
+    def configure
+      yield(configuration) if block_given?
+      configuration.validate! if block_given?
+      configuration
+    end
+
+    # Reset configuration (utile per test)
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Shortcut per check feature enabled
+    def enabled?(feature)
+      configuration.public_send("#{feature}_enabled?")
+    rescue NoMethodError
+      false
+    end
+  end
 end

metadata

@@ -1,17 +1,60 @@
 --- !ruby/object:Gem::Specification
 name: better_seo
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-05 00:00:00.000000000 Z
-dependencies: []
-description: BetterSeo provides tools and utilities to enhance SEO capabilities in
-  Ruby applications
+date: 2025-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: BetterSeo provides a clean, fluent DSL for managing meta tags, Open Graph,
+  Twitter Cards, and more. Features include automatic HTML generation, validation,
+  Rails view helpers, and 100% test coverage.
 email:
 - alessio@cosmic.tech
 executables: []
@@ -53,5 +96,5 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: A Ruby gem for better SEO functionality
+summary: Comprehensive SEO gem for Ruby and Rails applications
 test_files: []