Documentation
IntroductionThe 5-Step WorkflowThe Raw HTML StrategyJSON Drop-in SystemDynamic SitemapWhy Cryptomus?Anti-Spam LogicCommon Errors

The pSEO Wizard Manual 🧙‍♂️

Welcome to the complete technical guide for pSEO Wizard. This documentation condenses weeks of architectural decisions into a single workflow to help you launch 1,000+ pages safely.

💡 Quick Tip: Use the sidebar navigation to jump between sections, or scroll through the complete guide.

🚀 Part 1: The Core Workflow

Before diving into code, understand how the "Factory" works:

1. Project Configuration

Select your Target Language carefully. This sets the locale flag in the JSON output.

2. Pattern Logic

Use variables like {City} or {Service}. Keep patterns short for better SEO.

3. Data Generation

We use Cartesian Product logic. 10 Services × 10 Cities = 100 Pages.

🛡️ 4. The "Safety" Alert

In Step 4, we warn you to publish under /blog. Publishing programmatic content to the root domain is a fast way to get de-indexed by Google.

👨‍💻 Part 2: Developer Integration

The Gold Standard

📘 Note: The following guide recommends the best architecture for your Next.js application to handle our exported files.

The "Raw HTML" Strategy

Since pSEO Wizard generates full, styled HTML pages, wrapping them in a standard React Layout causes style conflicts.

✅ The Solution: We use a Next.js Route Handler to serve the HTML raw.

// src/app/[locale]/blog/[slug]/route.ts
export async function GET(request, { params }) {
  const post = getPostBySlug(params.slug);
  if (post.locale !== params.locale) return 404;
  
  const finalHtml = `<head><script src="https://cdn.tailwindcss.com"></script></head>
    <body>${post.body_html}</body>`;

  return new Response(finalHtml, { headers: { 'Content-Type': 'text/html' } });
}

The JSON Drop-in System

Forget database migrations. We built a system based on File System Aggregation.

  • 📁
    Directory: src/app/data/posts-json/
  • 🔄
    Workflow: Just "Drag & Drop" your exported JSON files here.
  • ✨
    Magic: The blog-posts.ts aggregator automatically reads all files and publishes them instantly.

Dynamic "Smart" Sitemap

Your sitemap.ts is locale-aware. It scans the JSON files and generates locale-specific URLs.

This prevents "Duplicate Content" penalties from Google.

🏛️ Part 3: Technical Architecture

Why Cryptomus?

We chose Cryptomus over Stripe for specific strategic reasons:

🌍 Global Reach

Accepts crypto payments from anywhere (solving regional banking restrictions and enabling global access).

⚡ Instant Unlock

The Webhook system unlocks the "Export" button instantly upon transaction confirmation.

Anti-Spam Architecture

Our system is designed to protect your domain authority:

  • All programmatic content lives under /blog subdirectory
  • Each page has unique, AI-generated content (no thin content)
  • Internal linking follows SEO best practices
  • Proper lang and dir attributes for multilingual content

🚑 Part 4: Troubleshooting

Common issues and their solutions:

❌ White Screen / Unstyled Text

Cause: Tailwind CDN is blocked.

Fix: Check next.config.js CSP headers. Allow cdn.tailwindcss.com.

⚠️ Broken Internal Links (/og/ or //)

Cause: AI generation artifacts.

Fix: Ensure your route.ts has the "Smart Regex" cleaner.

🔍 404 on Generated Posts

Cause: Slug mismatch (often Arabic encoding).

Fix: Ensure decodeURIComponent(slug) is used in your route handler.

✅ CTA Buttons Go to /blog

Cause: Regex replaces all links with blog path.

Fix: Use separate patterns for homepage links vs blog links.

Built with ❤️ by the pSEO Wizard Team

Last updated: December 2024

Documentation | pSEO Wizard