Documentation

Everything you need to go from keyword to ranking website.

Quick Start

git clone https://github.com/RichardDu1/seoplant.git
cd seoplant
pip install requests beautifulsoup4

# Analyze competitors
python scripts/competitor_intel.py report "your niche keyword"

# Generate SEO plan
python scripts/seo_engine.py plan "your niche keyword" --type website

# Scaffold Astro site
python scripts/site_builder.py scaffold ./my-site --name "My Site" --keyword "your niche"

# Build & preview
cd my-site && npm install && npm run dev

Pipeline Modules

1. Competitor Intelligence

Discovers competitors via Jina Search, crawls their websites, analyzes SEO signals (titles, meta, headings, schema, content depth), checks social media presence, and generates a SWOT report.

python scripts/competitor_intel.py report "best hiking boots"

2. SEO/GEO Engine

Expands keywords with heuristic patterns (or DataForSEO real data), clusters by topic and intent, assesses difficulty, generates a 6-month content calendar, and produces GEO configuration (llms.txt, Schema.org templates).

python scripts/seo_engine.py plan "scottish highlands travel" --type travel --langs en,zh

3. Design Intelligence

Searches design galleries (Awwwards, SiteInspire, Godly, Land-book, Mobbin) for niche-relevant inspiration, extracts design tokens (colors, fonts, spacing) from real websites, and fuses multiple designs into a unified DESIGN.md.

python scripts/design_intel.py search "travel website"
python scripts/design_intel.py extract "https://example.com"
python scripts/design_intel.py fuse --keywords "scotland travel" --type travel

4. Site Builder

Scaffolds a complete Astro 5.x project: BaseLayout, SEOHead, Header/Footer components, global CSS from DESIGN.md tokens, i18n routing, Schema.org structured data, robots.txt, sitemap config.

python scripts/site_builder.py scaffold ./my-site \
  --name "My Travel Site" \
  --keyword "scottish highlands travel" \
  --url "https://mysite.com" \
  --design DESIGN.md

5. Deployer

Deploys built sites to: customer VPS (SSH push with Caddy/Nginx bootstrap), Vercel, Cloudflare Pages, or generates manual deployment packages.

# One-click VPS deploy
python scripts/deployer.py deploy ./my-site mysite.com \
  --host 12.34.56.78 --user root --caddy

# Generate config files for manual setup
python scripts/deployer.py package ./my-site mysite.com --analytics

DataForSEO Integration

For real keyword data (search volume, CPC, competition, keyword difficulty), set environment variables:

export DATAFORSEO_EMAIL="your@email.com"
export DATAFORSEO_PASSWORD="your-api-password"

# Now seo_engine.py automatically uses real data
python scripts/seo_engine.py plan "best hiking boots" --type ecommerce

The DataForSEO client also provides standalone CLI access:

python scripts/dataforseo_client.py volume "hiking boots,trail shoes,camping gear"
python scripts/dataforseo_client.py related "best hiking boots"
python scripts/dataforseo_client.py serp "scottish highlands travel"
python scripts/dataforseo_client.py competitors "rei.com"

Deployment Options

Target	Command	Best For
Own VPS (Caddy)	`deploy ./site domain.com --host IP --caddy`	Full control, $5/mo
Own VPS (Nginx)	`deploy ./site domain.com --host IP --nginx`	Existing Nginx setups
Vercel	`vercel ./site`	Free tier, auto-SSL
Cloudflare Pages	`cloudflare ./site`	Global CDN, free tier
Manual	`package ./site domain.com`	Generate configs, DIY