Saman SEO

The Open Standard for WordPress SEO

A comprehensive, transparent SEO solution built for developers who believe SEO tooling should be open source, not a black box.

Why Open Source SEO?

For too long, WordPress SEO has been dominated by proprietary solutions that operate as black boxes. Each plugin guards its methods as trade secrets, fragmenting the ecosystem and forcing developers to work around opaque systems.

Saman SEO takes a different approach: We believe the SEO industry benefits from transparency, shared standards, and collaborative improvement. By open-sourcing our complete SEO workflow, we're establishing a foundation that the entire WordPress community can build upon, inspect, and enhance.

This is SEO without secrets—because better SEO comes from better collaboration, not better secrecy.

Features

Core SEO Management

• Per-Post SEO Fields: Complete meta control stored in _samanseo_meta with Gutenberg sidebar and classic editor support
• Server-Rendered Output: <title>, meta descriptions, canonical URLs, robots directives, Open Graph, Twitter Cards, and JSON-LD structured data
• Site-Wide Templates: Centralized defaults for titles, descriptions, social images, robots directives, and hreflang attributes
• Post-Type Granularity: Dedicated defaults for each content type—no more one-size-fits-all configurations

Advanced Capabilities

• AI-Powered Suggestions: OpenAI integration for intelligent title and meta description generation with customizable prompts and models
• Internal Linking Engine: Automated keyword-to-link conversion with rule-based controls, category targeting, and comprehensive previews
• Advanced Sitemap Manager: Full XML sitemap control with dedicated admin UI, post type/taxonomy selection, archive support, RSS & Google News sitemaps, custom pages, and scheduled regeneration
• Audit Dashboard: Visual severity graphs, issue logging, and automatic fallback generation for missing metadata
• Redirect Manager: Database-backed 301 redirects with WP-CLI support and 404 logging
• Developer Tools: Snippet previews, social media card previews, internal link suggestions, and compatibility detection

Content Analysis

• Real-Time Previews: SERP snippet and social media card simulations
• Link Opportunity Detection: AI-powered internal linking suggestions
• Quick Actions: Streamlined workflow for common SEO tasks
• Compatibility Checks: Automatic detection and graceful coexistence with other SEO plugins

Documentation

Getting Started

• Getting Started - Installation, configuration, and basic usage

Developer Resources

• Developer Guide - Filters, hooks, and programmatic control
• Filter Reference - Complete filter documentation with examples
• Template Tags & Shortcodes - Theme integration reference
• WP-CLI Commands - Command-line interface documentation

Feature Guides

• Sitemap Configuration - Advanced sitemap customization
• AI Assistant - AI-powered metadata generation
• Internal Linking - Automated internal link management
• Redirect Manager - 301 redirects and 404 monitoring
• Local SEO - Local business schema and settings

Quick Start

Installation

1. Download the latest release or clone this repository
2. Upload to /wp-content/plugins/wp-seo-pilot/
3. Activate through the WordPress admin interface
4. Navigate to Saman SEO → Defaults to configure site-wide settings

Basic Usage

Per-Post Configuration: Edit any post or page and locate the "Saman SEO" meta box or Gutenberg sidebar panel. Configure:

• SEO Title
• Meta Description
• Canonical URL
• Robots Directives
• Open Graph Image

Site-Wide Defaults: Navigate to Saman SEO → Defaults to set template-driven defaults that apply when per-post values aren't specified.

Developer Integration

Template Tags

// Render breadcrumbs in your theme
if ( function_exists( 'samanseo_breadcrumbs' ) ) {
    samanseo_breadcrumbs();
}

Programmatic Redirects

// Create a 301 redirect programmatically
$result = samanseo_create_redirect( '/old-url', '/new-url' );

if ( is_wp_error( $result ) ) {
    error_log( 'Redirect failed: ' . $result->get_error_message() );
}

Filter Hooks

// Modify SEO title dynamically
add_filter( 'saman_seo_title', function( $title, $post ) {
    if ( is_singular( 'product' ) ) {
        return $title . ' | Buy Now';
    }
    return $title;
}, 10, 2 );

// Override Open Graph image
add_filter( 'saman_seo_og_image', function( $image, $post ) {
    if ( $post && $post->ID === 42 ) {
        return 'https://cdn.example.com/special-image.jpg';
    }
    return $image;
}, 10, 2 );

For comprehensive filter documentation, see docs/FILTERS.md.

WP-CLI Support

# List all redirects
wp saman-seo redirects list --format=table

# Export redirects to JSON
wp saman-seo redirects export redirects.json

# Import redirects from JSON
wp saman-seo redirects import redirects.json

Full WP-CLI documentation: docs/WP_CLI.md

Contributing

We welcome contributions from the community. Whether you're fixing bugs, adding features, improving documentation, or suggesting enhancements, your input helps establish better standards for WordPress SEO.

See CONTRIBUTING.md for guidelines.

Privacy & Security

• 404 Logging: Opt-in feature that stores only hashed referrers
• No Telemetry: Zero external tracking or analytics
• No External Requests: All processing happens on your server (except optional AI features when explicitly enabled)

Asset Development

The plugin uses Less for stylesheet compilation.

# Install dependencies
npm install

# Build CSS from Less sources
npm run build

# Watch for changes during development
npm run watch

Support

• Issues: GitHub Issues
• Documentation: Full Documentation
• Community: Discussions

Built with transparency. Built for the community. Built to be better.