Skip to content

README.md

Latest commit

 

History

History
183 lines (128 loc) · 5.24 KB

README.md

File metadata and controls

183 lines (128 loc) · 5.24 KB
Raw

Programmatic SEO Toolkit

Languages: English | Español

GitHub description (short):
Rule-based programmatic SEO planner — GSC + crawl data → prioritized URL opportunities (CSV/YAML). Works standalone or with SEO-as-Code and AI-SEO-Toolkit.

Quick test (no credentials, no parent repo)

Anyone can test in under 2 minutes with bundled sample data:

git clone https://github.com/seo-as-code/programmatic-SEO.git
cd programmatic-SEO
pip install -r requirements.txt
copy config\project.local.yaml.example config\project.local.yaml   # Windows
# cp config/project.local.yaml.example config/project.local.yaml   # macOS/Linux
python scripts/planner/pseo_planner.py

Or:

.\reports\code\run_planner.ps1

Expected output in reports/pseo/:

  • pseo_queries_*.csv — one row per GSC query
  • pseo_opportunities_*.csv — clustered URL opportunities
  • pseo_opportunities_*.yaml — machine-readable page specs
  • pseo_summary_*.md — human-readable summary

Configure your site

  1. Copy config/project.local.yaml.example → config/project.local.yaml
  2. Copy config/patterns.local.yaml.example → config/patterns.local.yaml (optional but recommended)
  3. Edit only *.local.yaml files (gitignored, never pushed)
File Purpose
project.local.yaml Site URL, locale, paths to GSC/SF CSV
patterns.local.yaml Your services, cities, custom pattern rules

config/project.yaml and config/patterns.yaml on GitHub stay generic.

1. What this repository does

Programmatic SEO Toolkit is the architecture layer of the SEO-as-Code stack:

  • Reads GSC queries + crawl inventory (Screaming Frog)
  • Applies YAML pattern rules (services, locations, intents)
  • Outputs prioritized URL opportunities with actions: create_new, optimize_existing, consolidate, ignore

No AI required. No Ahrefs. Deterministic and reproducible.

2. How the three repositories work together

SEO-as-Code-Toolkit (Data)
  ├─ GSC, GA4, CrUX, Screaming Frog → data/raw/*.csv
  └─ Index monitor (separate folder in monorepo)

Programmatic-SEO (Architecture)  ← this repo
  ├─ GSC + SF + pattern rules
  └─ reports/pseo/*.yaml → URL specs for devs/CMS

AI-SEO-Toolkit (Decision)
  ├─ Semantic map, gaps, blog strategy, executive report
  └─ Optional copy briefs on top of pSEO specs
Handoff File From → To
GSC export ../data/raw/gsc_*.csv SEO-as-Code → pSEO Planner
Crawl export ../data/raw/internos_html.csv SEO-as-Code → pSEO Planner
Opportunities reports/pseo/pseo_opportunities_*.yaml pSEO → dev/CMS or AI module 12

3. Repository structure

programmatic-seo/
  config/
    project.yaml              # generic site placeholders
    patterns.yaml             # generic pattern rules
    project.local.yaml.example
    patterns.local.yaml.example
  data/samples/               # demo GSC + SF (committed)
  scripts/
    lib/                      # config loader + rule engine
    planner/pseo_planner.py   # main CLI
    orchestrator/pseo_master.py
  reports/
    pseo/                     # generated (gitignored)
    code/                     # run_planner.ps1, run_with_seo_as_code.ps1
  templates/                  # page spec examples for CMS
  docs/PLAYBOOK.md

4. Commands

Standalone (samples)

cd programmatic-seo
.\reports\code\run_planner.ps1

Inside SEO-as-Code monorepo

cd C:\path\to\proyecto_seo\programmatic-seo
.\reports\code\run_with_seo_as_code.ps1

Manual paths

py .\scripts\planner\pseo_planner.py --gsc ..\data\raw\gsc_oauth_2026-01-01_2026-02-01.csv --sf ..\data\raw\internos_html.csv

5. Pattern rules (summary)

Defined in config/patterns.yaml + patterns.local.yaml:

Pattern Triggers Suggested URL
service_location service + city tokens /services/{service}-{city}/
service_national service, no geo /services/{service}/
blog_informational how/what/guide queries /blog/{query-slug}/
brand_navigational brand intent ignore

Decision rules override patterns: hub weakness, cannibalization, low volume, etc.

Full guide: docs/PLAYBOOK.md

6. Actions explained

Action When
create_new Demand exists, no dedicated URL
optimize_existing URL exists but underperforms
consolidate Same query split across multiple URLs
ignore Low volume or out of scope

7. What NOT to commit

See .gitignore:

  • config/project.local.yaml
  • config/patterns.local.yaml
  • reports/pseo/*.csv, *.yaml, *.md
  • .venv/

8. Related repositories

License

MIT — use freely in client and personal projects.