seo-sitemap

Sitemap Analysis & Generation

Mode 1: Analyze Existing Sitemap

Discover candidates before reporting a sitemap missing:

seogeo sitemap-discovery  --json

The helper reads every bounded Sitemap: declaration in robots.txt, validates cross-host targets through the shared SSRF-safe fetch layer, and still probes common paths when a declared sitemap is stale or invalid. Use only entries in found; preserve declared failures as findings instead of treating a robots.txt line alone as proof that a sitemap works.

Validation Checks

• Valid XML format
• Per-file limit: ≤50,000 URLs AND ≤50MB uncompressed (whichever is hit first)
• All URLs return HTTP 200
• accurate: must be a valid **W3C Datetime** and reflect the **last significant content change** (main content, structured data, links, not copyright/boilerplate edits). Google only honours when consistently and verifiably accurate, so warn when values are suspiciously uniform or newer than the page's real content.
• No deprecated tags: and are ignored by Google
• Sitemap referenced in robots.txt
• Compare crawled pages vs sitemap; flag missing pages

Quality Signals

• Sitemap index file if >50k URLs
• Split by content type (pages, posts, images, videos)
• No non-canonical URLs in sitemap
• No noindexed URLs in sitemap
• No redirected URLs in sitemap
• HTTPS URLs only (no HTTP)

Common Issues

Extension sitemaps (image / video / news)

Google documents three subtypes with their own rules, validate per-subtype:

• Image (http://www.google.com/schemas/sitemap-image/1.1): only two valid tags remain, and (max 1,000 per). /// were deprecated (2022), flag as info-level removable.
• Video: required with, , , plus or; mRSS also supported. Flag deprecated/removed tags (, , , , player autoplay/allow_embed) as info-level removable; recheck Google docs before citing a removal date.
• News: max 1,000 per file (not 50,000); include only articles from the **last 2 days**; required// //; submit/discover through Search Console or robots.txt/sitemap index; use Publisher Center only for publication management where relevant. When the news: namespace is detected, override the generic 50k check with the 1,000 cap.

Mode 2: Generate New Sitemap

Process

1. Ask for business type (or auto-detect from existing site)
2. Load industry template from ../seo-plan/assets/ directory
3. Interactive structure planning with user
4. Apply quality gates:
   • ⚠️ WARNING at 30+ location pages (require 60%+ unique content)
   • 🛑 HARD STOP at 50+ location pages (require justification)
5. Generate valid XML output
6. Split at whichever comes first: 50,000 URLs or 50MB uncompressed, with sitemap index
7. Generate STRUCTURE.md documentation

Safe Programmatic Pages (OK at scale)

✅ Integration pages (with real setup docs) ✅ Template/tool pages (with downloadable content) ✅ Glossary pages (200+ word definitions) ✅ Product pages (unique specs, reviews) ✅ User profile pages (user-generated content)

Penalty Risk (avoid at scale)

❌ Location pages with only city name swapped ❌ "Best [tool] for [industry]" without industry-specific value ❌ "[Competitor] alternative" without real comparison data ❌ AI-generated pages without human review and unique value

Sitemap Format

Standard Sitemap

<?xml version="1.0" encoding="UTF-8"?>

  
    https://example.com/page
    2026-02-07
  

Sitemap Index (for >50k URLs)

<?xml version="1.0" encoding="UTF-8"?>

  
    https://example.com/sitemap-pages.xml
    2026-02-07
  
  
    https://example.com/sitemap-posts.xml
    2026-02-07
  

Error Handling

• URL unreachable: Report the HTTP status code and suggest checking if the site is live
• No sitemap found: Run seogeo sitemap-discovery and report "not found" only when its found list is empty after declared and common candidates are checked
• Invalid XML format: Report specific parsing errors with line numbers
• Rate limiting detected: Back off and report partial results with a note about retry timing

Output

For Analysis

• VALIDATION-REPORT.md: analysis results
• Issues list with severity
• Recommendations

For Generation

• sitemap.xml (or split files with index)
• STRUCTURE.md: site architecture documentation
• URL count and organization summary

---

Tooling

# Find every sitemap: robots.txt declarations plus the well-known paths
seogeo sitemap-discovery https://example.com --json

# Pull the URL list out of the discovered sitemaps
seogeo crawl-sitemap https://example.com --max-pages 500 --json

# What Search Console thinks of the submitted sitemaps
seogeo gsc-sitemaps --property https://example.com/ --json

sitemap-discovery reports every candidate it checked, not just the ones that worked, so a 404 on /sitemap.xml is visible rather than silent. Each entry carries kind (urlset, sitemapindex, rss, feed, text) and, on failure, a specific error.

Two safety behaviours worth knowing when you read the output:

• Sitemaps declared in robots.txt may legitimately live on another host. Those are fetched, but flagged with cross_host: true.
• Query strings are stripped from displayed URLs and the entry is marked query_redacted, so a signed sitemap URL never lands in a report.

crawl-sitemap follows `` entries into their child sitemaps automatically and stops at --max-pages.