general pseo-url-structure

pseo-url-structure

This skill should be used when the user asks to "design URLs for pSEO", "URL structure for programmatic pages", "pSEO URL patterns", "URL format for scaled content", "programmatic SEO URL design", "slug format for pSEO", "how to structure URLs for pSEO", "URL architecture for programmatic pages", or any variation of designing, structuring, or optimizing URL patterns for programmatic SEO pages at scale.
Download .md

pSEO URL Structure

URL structure for programmatic SEO defines how hundreds or thousands of pages are organized, named, and discoverable. Good URL structure makes pages crawlable, creates clear hierarchy, prevents duplicate content, and signals to Google what each page is about. Bad URL structure creates crawl traps, duplicate content issues, and confuses both search engines and users.

For pSEO specifically, URL decisions are made once but apply to every page in the set. A wrong decision at scale is 500 wrong URLs, not just one.

URL Pattern Templates by Page Type

Page type URL pattern Example
Integration pages /integrations/{tool-name} /integrations/salesforce
Glossary/definitions /glossary/{term} /glossary/lead-scoring
Comparison pages /vs/{product-a}-vs-{product-b} /vs/hubspot-vs-salesforce
Alternatives pages /alternatives/{competitor}-alternatives /alternatives/salesforce-alternatives
City/location pages /{service}/{city} or /{service}/{state}/{city} /marketing-agencies/california/san-francisco
Tool directory /tools/{category}/{tool-name} /tools/crm/hubspot
Use case pages /use-cases/{use-case} /use-cases/saas-sales-teams
Template pages /templates/{template-type} /templates/cold-email-sequence
Category listing (hub) /{page-type}/ /integrations/

URL Design Rules

Rule 1: Static paths only — no URL parameters

Bad (parameters) Good (static paths)
/page?type=integration&id=salesforce /integrations/salesforce
/compare?a=hubspot&b=salesforce /vs/hubspot-vs-salesforce
/glossary?term=lead-scoring /glossary/lead-scoring

Why: URL parameters create duplicate content risk, are harder for Google to crawl, and look less trustworthy to users.

Rule 2: Include the target keyword in the URL

Bad (no keyword) Good (keyword present)
/p/42 /integrations/salesforce
/tools/item-389 /tools/crm/hubspot
/content/entry-lead-scoring /glossary/lead-scoring

Rule 3: Lowercase, hyphens, no special characters

Rule Bad Good
Lowercase /Integrations/Salesforce /integrations/salesforce
Hyphens between words /glossary/lead_scoring /glossary/lead-scoring
No special characters /tools/crm%20tools /tools/crm
No trailing slash (or always — pick one) Mix of /tools/crm and /tools/crm/ Pick one convention, enforce it site-wide
No file extensions /glossary/lead-scoring.html /glossary/lead-scoring

Rule 4: Maximum 3 levels of depth

Bad (too deep) Good (≤ 3 levels)
/resources/tools/category/crm/reviews/hubspot (5 levels) /tools/crm/hubspot (3 levels)
/content/library/glossary/terms/marketing/lead-scoring (6 levels) /glossary/lead-scoring (2 levels)

Why: Deeper URLs get crawled less frequently and rank lower.

Rule 5: Parent directory exists as a real page

Every parent path must be a real, accessible page.

URL Parent path Parent page must exist?
/integrations/salesforce /integrations/ Yes — this is the hub/listing page
/vs/hubspot-vs-salesforce /vs/ Yes — comparison directory page
/glossary/lead-scoring /glossary/ Yes — glossary index page

Why: If /integrations/ returns a 404, Google can't discover /integrations/salesforce through directory crawling.


Handling URL Variations

Alphabetical ordering for comparison pages

For "[X] vs [Y]" pages, always alphabetize to prevent duplicates:

Situation Wrong (creates duplicates) Right (one canonical URL)
HubSpot vs Salesforce Both /vs/hubspot-vs-salesforce AND /vs/salesforce-vs-hubspot /vs/hubspot-vs-salesforce only. Redirect the reverse

Rule: Alphabetize by first product name. Redirect all reverse-order variations with a 301.

Singular vs plural

Pick one convention and enforce it:

Convention Example When to use
Plural for directories /integrations/, /tools/, /templates/ When the directory contains multiple items
Singular for entries /integrations/salesforce (not /integration/salesforce) Keep directory plural, entry singular by removing the "s" is confusing — keep the parent consistent

Recommendation: Use plural for the directory path. /integrations/salesforce reads naturally as "the Salesforce page within our integrations."

Geographic URLs

Approach Pattern When to use
City only /agencies/{city} When you cover one country
State + city /agencies/{state}/{city} When cities share names across states
Country + city /agencies/{country}/{city} International pSEO

Canonicalization for pSEO

Self-referencing canonicals

Every pSEO page must have a self-referencing canonical tag:

<link rel="canonical" href="https://yourdomain.com/integrations/salesforce" />

Handling pagination

For paginated listing pages (hub pages with 100+ entries):

Approach Implementation Recommendation
Paginated pages /integrations/, /integrations/page/2/, /integrations/page/3/ Use with rel="next" / rel="prev"
Load more / infinite scroll All entries on one URL, loaded dynamically Must render all items in HTML for crawling
View all page Single page with all entries Only viable for < 200 entries

Recommendation: Paginated pages with 50-100 items per page. Include pagination links in the HTML (not just JavaScript).


Pre-Build Checklist

  • [ ] URL pattern defined for each pSEO page type
  • [ ] URL convention documented (lowercase, hyphens, no trailing slash)
  • [ ] Parent directory pages exist for every URL path
  • [ ] Maximum depth is 3 levels or fewer
  • [ ] Target keyword present in every URL
  • [ ] Alphabetical ordering rule set for comparison pages
  • [ ] Redirect rules defined for URL variations (reverse order, trailing slash, etc.)
  • [ ] Self-referencing canonical tags implemented on every page
  • [ ] Pagination strategy chosen for hub/listing pages
  • [ ] 301 redirects configured for any URL pattern changes
  • [ ] URL generation logic automated (no manual slug creation)

Anti-Pattern Check

  • URL parameters instead of static paths → /page?id=42 tells Google nothing about the content and creates duplicate content risk. Use descriptive static paths: /integrations/salesforce
  • Inconsistent URL conventions → Mixing /Integrations/Salesforce, /integrations/salesforce/, and /integration/salesforce creates confusion and potential duplicates. Define one convention and enforce it in code
  • No parent directory page → If /integrations/salesforce exists but /integrations/ returns 404, many pSEO pages won't be discovered by crawlers. Build hub pages for every parent path
  • Both /vs/a-vs-b and /vs/b-vs-a exist → This creates duplicate content. Alphabetize, pick one canonical URL, and 301 redirect the other
  • URLs 5+ levels deep → Deep URLs get crawled less. Keep to 3 levels maximum. Flatten your hierarchy if needed
  • Manual slug creation for 500 pages → Human error at scale creates inconsistency. Automate URL generation from the data source with coded convention rules
Want agents that use skill files like this?
We customize skill files for your brand voice and methodology, then run content agents against them.
Book a call