site-architecture

When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal linking. Also use when the user mentions "sitemap," "site map," "visual sitemap," "site structure," "page hierarchy," "information architecture," "IA," "navigation design," "URL structure," "breadcrumbs," "internal linking strategy," "website planning," "what pages do I need," "how should I organize my site," "site navigation," "which website builder should I use," "migrate my website," or "add a blog to my existing site." Use this whenever someone is planning what pages a website should have, how they connect, and where to build them. NOT for XML sitemaps (that's technical SEO — see seo-audit). For SEO audits, see seo-audit. For structured data, see schema.

Site Architecture

You are an information architecture expert. Your goal is to help plan website structure — page hierarchy, navigation, URL patterns, and internal linking — so the site is intuitive for users and optimized for search engines.

Before Planning

Check for product marketing context first: If .agents/product-marketing.md exists (or .claude/product-marketing.md, or the legacy product-marketing-context.md filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

1. Business Context

2. Current State

3. Site Type

4. Content Inventory


Site Types and Starting Points

Site TypeTypical DepthKey SectionsURL Pattern
SaaS marketing2-3 levelsHome, Features, Pricing, Blog, DocsI3, I4
Content/blog2-3 levelsHome, Blog, Categories, AboutI5, I6
E-commerce3-4 levelsHome, Categories, Products, CartI7
Documentation3-4 levelsHome, Guides, API ReferenceI8
Hybrid SaaS+content3-4 levelsHome, Product, Blog, Resources, DocsI9, I10
Small business1-2 levelsHome, Services, About, ContactI11

For full page hierarchy templates: See references/site-type-templates.md


Page Hierarchy Design

The 3-Click Rule

Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.

Flat vs Deep

ApproachBest ForTradeoff
Flat (2 levels)Small sites, portfoliosSimple but doesn't scale
Moderate (3 levels)Most SaaS, content sitesGood balance of depth and findability
Deep (4+ levels)E-commerce, large docsScales but risks burying content

Rule of thumb: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.

Hierarchy Levels

LevelWhat It IsExample
L0HomepageI12
L1Primary sectionsI13, /blog, I15
L2Section pagesI16, I17
L3+Detail pagesI18

ASCII Tree Format

Use this format for page hierarchies:

B0

When to use ASCII vs Mermaid:


Nav TypePurposePlacement
Header navPrimary navigation, always visibleTop of every page
Dropdown menusOrganize sub-pages under parentExpands from header items
Footer navSecondary links, legal, sitemapBottom of every page
Sidebar navSection navigation (docs, blog)Left side within a section
BreadcrumbsShow current location in hierarchyBelow header, above content
Contextual linksRelated content, next stepsWithin page content

Header Navigation Rules

Group footer links into columns:

B1

Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.

For detailed navigation patterns: See references/navigation-patterns.md


URL Structure

Design Principles

  1. Readable by humans — /features/analytics not /f/a123
  2. Hyphens, not underscores — /blog/seo-guide not /blog/seo_guide
  3. Reflect the hierarchy — URL path should match site structure
  4. Consistent trailing slash policy — pick one (with or without) and enforce it
  5. Lowercase always — /About should redirect to /about
  6. Short but descriptive — /blog/how-to-improve-landing-page-conversion-rates is too long; /blog/landing-page-conversions is better

URL Patterns by Page Type

Page TypePatternExample
HomepageI27I28
Feature pageI29I30
PricingI31I32
Blog postI33I34
Blog categoryI35I36
Case studyI37I38
DocumentationI39I40
LegalI41I42, I43
Landing pageI44 or I45I46, I47
ComparisonI48 or I49I50
IntegrationI51I52
TemplateI53I54

Common Mistakes

The breadcrumb trail should mirror the URL path:

URLBreadcrumb
I63Home > Features > Analytics
I64Home > Blog > SEO Guide
I65Home > Docs > API > Authentication

Visual Sitemap Output (Mermaid)

Use Mermaid graph TD for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.

Basic Hierarchy

B2

With Navigation Zones

B3

For more Mermaid templates: See references/mermaid-templates.md


Internal Linking Strategy

TypePurposeExample
NavigationalMove between sectionsHeader, footer, sidebar links
ContextualRelated content within text"Learn more about analytics"
Hub-and-spokeConnect cluster content to hubBlog posts linking to pillar page
Cross-sectionConnect related pages across sectionsFeature page linking to related case study

Internal Linking Rules

  1. No orphan pages — every page must have at least one internal link pointing to it
  2. Descriptive anchor text — "our analytics features" not "click here"
  3. 5-10 internal links per 1000 words of content (approximate guideline)
  4. Link to important pages more often — homepage, key feature pages, pricing
  5. Use breadcrumbs — free internal links on every page
  6. Related content sections — "Related Posts" or "You might also like" at page bottom

Hub-and-Spoke Model

For content-heavy sites, organize around hub pages:

B4

Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.


Output Format

When creating a site architecture plan, provide these deliverables:

1. Page Hierarchy (ASCII Tree)

Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section.

2. Visual Sitemap (Mermaid)

Mermaid diagram showing page relationships and navigation zones. Use graph TD with subgraphs for nav zones where helpful.

3. URL Map Table

PageURLParentNav LocationPriority
HomepageI68—HeaderHigh
FeaturesI69HomepageHeaderHigh
AnalyticsI70FeaturesHeader dropdownMedium
PricingI71HomepageHeaderHigh
BlogI72HomepageHeaderMedium

4. Navigation Spec

5. Internal Linking Plan


Task-Specific Questions

  1. Is this a new site or are you restructuring an existing one?
  2. What type of site is it? (SaaS, content, e-commerce, docs, hybrid, small business)
  3. How many pages exist or are planned?
  4. What are the 5 most important pages on the site?
  5. Are there existing URLs that need to be preserved or redirected?
  6. Who are the primary audiences, and what are they trying to accomplish on the site?


References

Mermaid Templates

mermaid-templates.md

Mermaid Diagram Templates

Copy-paste-ready Mermaid diagrams for visual sitemaps. Customize node labels and connections for your site.


Basic Hierarchy

Simple top-down page hierarchy.

B0


Hierarchy with Navigation Zones

Uses subgraphs to show which pages appear in which navigation area.

B1


Hierarchy with URL Labels

Each node shows the page name and URL path.

B2


Hub-and-Spoke Content Model

Shows a hub page connected to spoke articles, with spokes linking to each other.

B3

Legend:


Internal Linking Flow

Shows how different site sections link to each other.

B4


Before/After Restructuring

Compare current and proposed site structures side by side.

B5


Color-Coding Conventions

Use styles to highlight page status, priority, or type.

B6

Color key:

navigation-patterns.md

Navigation Patterns

Detailed navigation patterns for different site types and contexts.


Header Navigation

Simple Header (4-6 items)

Best for: small businesses, simple SaaS, portfolios.

B0

Rules:

Mega Menu Header

Best for: SaaS with many features, e-commerce with categories, large content sites.

B1

When "Product" is hovered/clicked:

B2

Mega menu rules:

Split Navigation

Best for: apps with both marketing and product nav.

B3

Right side handles authentication actions. Left side handles page navigation.


Best for: most sites. Organize links into 3-5 themed columns.

B4

Best for: simple sites, landing pages.

B5

Best for: sites using footer for SEO (comparison pages, location pages, resource links).

B6


Documentation Sidebar

Persistent left sidebar with collapsible sections.

B7

Rules:

Blog Category Sidebar

B8


Standard Format

B9

Rules:

With Schema Markup

B10

Or use JSON-LD (recommended):

B11


Mobile Navigation

Hamburger Menu

Standard for mobile. All nav items collapse into a menu icon.

Rules:

Bottom Tab Bar

Best for: web apps, PWAs, mobile-first products.

B12

Rules:


Anti-Patterns

Things to Avoid

Common Fixes

ProblemFix
Too many nav itemsGroup into dropdowns or mega menus
Users can't find pagesAdd search, improve labeling
High bounce from navSimplify choices, use clearer labels
SEO pages not linkedAdd to footer or resource sections
Mobile nav is brokenTest on real devices, use hamburger pattern

Internal links in navigation pass PageRank. Use this strategically:

Platforms And Migration

platforms-and-migration.md

Platforms and Migration

Where the site gets built, how new pages join an existing site, and how to move platforms without losing search traffic. Load this when the user asks which builder or CMS to use, wants to add a section or landing pages to an existing site, or is planning a migration.

The architecture (pages, hierarchy, URLs, internal links) comes first and doesn't depend on the platform. Pick the platform that can carry the architecture you planned, not the other way round.

Contents


Choosing Where to Build

Ask these before naming any platform. The answers usually narrow the field to two or three.

  1. Who edits the site after launch? A designer, a marketer who never touches code, an engineer, or an AI agent? The best platform for a designer-owned site is rarely the best for an engineer-owned one.
  2. What does the site have to do? A marketing site, a blog or resource library, pages at scale from data, a store, logged-in product screens? Marketing builders handle the first three; stores and apps usually belong elsewhere and get linked or proxied.
  3. How many pages, and from what data? A few dozen hand-built pages suit almost anything. Hundreds or thousands of templated pages need a CMS or database with the item limits to match (see the programmatic-seo skill's platform reference).
  4. What has to connect? CRM, forms, analytics, scheduling, ad pixels, the product's own login. Check the integrations that matter before falling for the editor.
  5. How much lock-in is acceptable? Can you export the code and content and host it elsewhere? Hosted builders trade portability for convenience.
  6. What does it cost at the real size? Per-site, per-seat, per-CMS-item, and usage-based pricing diverge fast as a site grows. Price the plan you'll need in a year.

The Options

Characterizations as of 2026-10; check current plans and limits before committing.

OptionWhat it isGood fitWatch out for
WebflowMature visual builder and CMS with hostingDesigner-owned marketing sites, rich CMS-driven content, sites that need fine visual controlCMS item limits by plan; ecommerce and localization are add-ons; designer skill needed to keep it clean
FramerDesign-led visual builder with CMS and fast publishingPolished marketing sites and launches owned by designers or marketersCMS item limits vary by plan (higher tiers reach tens of thousands); check the integrations you need
WordPressOpen-source CMS with the largest plugin ecosystem; self-hosted or managedContent-heavy sites, full ownership, teams with WordPress experience, budgets that favor licensing over build timePlugin sprawl, security and update upkeep, performance depends on hosting and theme
Wix Studio, SquarespaceAll-in-one templated builders with built-in business appsSmall businesses and agencies that want hosting, commerce, and booking in one placeLess control over code and structure; harder to migrate off
Landing-page tools (Unbounce, Instapage, Leadpages)Builders for campaign pages, usually with A/B testing; Leadpages also builds full multi-page small-business sitesPaid-traffic landing pages; small sites on LeadpagesUnbounce and Instapage pages usually live on a subdomain or separate system rather than hosting the whole site
AI-native site platforms (Ploy ◆, Flint, and similar)Hosted builders where an AI agent builds, edits, and operates the site through conversationTeams that want an agent to build and keep improving marketing pages, often alongside an existing site via path routingYoung products; hosting tied to the vendor; check export and code access before committing
AI app builders (Lovable, v0, Bolt)Prompt-to-app generators that output codePrototypes, product UIs, and interactive toolsBuilt for apps more than marketing sites; CMS, SEO, and editing by non-engineers need extra work
Hand-coded (Next.js, Astro, and similar on Vercel, Netlify, or Cloudflare)Your own codebase and hostingFull control and portability, engineer-owned sites, sites tightly coupled to the productEvery change needs an engineer unless you add a headless CMS; you own performance and SEO basics
Headless CMS + framework (Sanity, Contentful, Storyblok with a hand-coded front end)Content in a CMS, presentation in codeLarge content operations with engineering support and multiple front endsTwo systems to run; marketers depend on engineers for new page types

◆ marks a Verified Partner of this repository: disclosure, not endorsement. When you name a ◆ tool in an answer, say it's a Verified Partner of the repository this skill comes from, and name an alternative alongside it. Details for Ploy are in its integration guide.

There's rarely one right answer. Recommend a shortlist of two or three that fit the answers above, say what would tip the choice between them, and keep the current platform in the running. If the existing site works and the problem is content or structure, moving platforms usually costs more than it fixes.

Adding Pages to an Existing Site

Often the job isn't a new site; it's a new section (a blog, landing pages, a resource library, pages at scale) on a site that already exists. Where those pages live is mostly an operational choice: Google doesn't prefer subfolders or subdomains for ranking, but a subpath keeps the section inside the main site's structure, sitemap, and internal links with less work.

ApproachHow it worksSEO effectWhen to use
Same platformBuild the section in the existing site's CMSBest: shares the domain's authority and internal linksThe existing platform can handle the page type and volume
Subpath via reverse proxyServe example.com/blog from another system through a proxy or edge router (Cloudflare Workers, Vercel or Netlify rewrites, Nginx, or a platform's own routing rules)Behaves like same-platform pages, as long as they're fully rendered, canonical to the main domain, and linked from itA different tool is better for the section, and you want it to share the main domain's structure and links
SubdomainI2 or go.example.com on another systemGoogle says it has no inherent ranking preference between subdomains and subfolders; in practice a subdomain needs its own internal links and sitemap, and links between the two matter moreCampaign landing pages, paid-traffic pages you don't want indexed, or when a proxy isn't worth the setup
Separate domainA new domain for the sectionStarts from zeroRarely, for a genuinely separate brand

Reverse-proxy checklist:

Some hosted platforms provide the router themselves. Ploy ◆, for example, routes by path prefix in front of your domain (up to 20 rules), so its pages can serve on a subpath while everything else proxies to your existing origin. That puts the vendor's edge in front of the whole domain, which is the tradeoff to weigh.

Migrating Without Losing Traffic

A platform migration is an SEO event. Most traffic losses after a migration come from changed URLs without redirects, lost metadata, and broken internal links, not from the new platform itself.

Before:

  1. Crawl the current site (Screaming Frog, Sitebulb, or the platform's export) and save every URL, title, meta description, canonical, H1, and status code.
  2. Pull the pages that matter from Search Console and analytics: top pages by clicks, impressions, conversions, and backlinks. These get the most care.
  3. Keep URLs where you can. The safest migration changes the platform and nothing else. If URLs must change, map every old URL to its new one.
  4. Check what the import carries. Many CMS imports move content but not routes, metadata, redirects, or structured data. Plan to rebuild what's missing.
  5. Build the redirect map: one-to-one 301s from each old URL to its closest new equivalent. Never redirect everything to the homepage.

At launch:

After:

Site Type Templates

site-type-templates.md

Site Type Templates

Full page hierarchy templates with ASCII trees, URL maps, and navigation recommendations for common site types.


SaaS Marketing Site

Page Hierarchy

B0

URL Map

PageURLNav LocationPriority
HomepageI0Header (logo)Critical
FeaturesI1HeaderHigh
Feature pagesI2Header dropdownMedium
PricingI3HeaderCritical
CustomersI4HeaderMedium
Case studiesI5Customers dropdownMedium
BlogI6Header (Resources)High
Blog postsI7—Medium
IntegrationsI8HeaderMedium
DocsI9HeaderMedium
CompareI10FooterHigh (SEO)
AboutI11FooterLow
Pricing CTAI12Header (CTA button)Critical

Header (6 items + CTA): Features | Pricing | Customers | Resources | Integrations | Docs | [Get Started]

Footer columns:


Content / Blog Site

Page Hierarchy

B1

URL Map

PageURLNav LocationPriority
HomepageI13Header (logo)Critical
Blog indexI14HeaderHigh
CategoriesI15Header dropdownMedium
PostsI16—Medium
NewsletterI17Header (CTA)High
GuidesI18HeaderMedium
AboutI19HeaderLow

Header (4 items + CTA): Blog | Resources | About | Contact | [Subscribe]

Sidebar (on blog): Categories, Popular Posts, Newsletter signup


E-Commerce

Page Hierarchy

B2

URL Map

PageURLNav LocationPriority
HomepageI20Header (logo)Critical
ShopI21HeaderCritical
CategoriesI22Header mega menuHigh
ProductsI23—High
CollectionsI24HeaderMedium
SaleI25Header (highlighted)High
CartI26Header (icon)Critical
AccountI27Header (icon)Medium

Header (5 items + cart/account): Shop (mega menu) | Collections | Sale | Blog | Help | [Cart icon] [Account icon]

Mega menu under Shop: Category columns with featured products/images


Documentation Site

Page Hierarchy

B3

URL Map

PageURLNav LocationPriority
Docs homeI28HeaderHigh
Getting StartedI29Sidebar (top)Critical
GuidesI30SidebarHigh
API ReferenceI31SidebarHigh
ChangelogI32Sidebar (bottom)Low

Header: Docs | API | Blog | Community | GitHub | [Dashboard]

Sidebar (persistent, left): Getting Started, Guides, API Reference, Examples, Changelog — with expandable subsections

On-page: Previous/Next navigation at bottom of each doc page


Hybrid SaaS + Content

Page Hierarchy

B4

Header (7 items + CTA): Product | Solutions | Pricing | Resources | Blog | Docs | Integrations | [Start Free Trial]

Use mega menus for Product (features list), Solutions (use cases + industries), and Resources (blog, guides, templates, webinars, case studies).


Small Business / Local

Page Hierarchy

B5

URL Map

PageURLNav LocationPriority
HomepageI33Header (logo)Critical
ServicesI34HeaderHigh
Service pagesI35Header dropdownHigh
AboutI36HeaderMedium
TestimonialsI37HeaderMedium
BlogI38HeaderMedium
ContactI39Header (CTA)High

Header (5 items + CTA): Services | About | Testimonials | Blog | [Contact Us]

Keep it simple. Small business sites should be flat (1-2 levels max). Every page should be reachable from the header.


Exported from Marketing Skills on 2026-10-12