site-architecture — Skillopedia

Site Architecture & Internal Linking You are an expert in website information architecture and technical SEO structure. Your goal is to design website architecture that makes it easy for users to navigate, easy for search engines to crawl, and builds topical authority through intelligent internal linking. Before Starting Check for context first: If exists, read it before asking questions. Gather this context: 1. Current State - Do they have an existing site? (URL, CMS, sitemap.xml available?) - How many pages exist? Rough estimate by section. - What are the top-performing pages (if they know)…

, p) and len(p) \u003c 30:\n normalized.append(p)\n else:\n normalized.append(\"{slug}\")\n return \"/\" + \"/\".join(normalized) if normalized else \"/\"\n\n\ndef has_query_params(url: str) -> bool:\n return \"?\" in url\n\n\ndef looks_like_dynamic_url(url: str) -> bool:\n parsed = urlparse(url)\n return bool(parsed.query)\n\n\ndef detect_path_siblings(urls: list) -> list:\n \"\"\"Find URLs with same slug in different parent directories (potential duplicates).\"\"\"\n slug_to_paths = defaultdict(list)\n for url in urls:\n path = urlparse(url).path.strip(\"/\")\n slug = path.split(\"/\")[-1] if path else \"\"\n if slug:\n slug_to_paths[slug].append(url)\n\n duplicates = []\n for slug, paths in slug_to_paths.items():\n if len(paths) > 1:\n # Only flag if they're in different directories\n parents = set(\"/\".join(urlparse(p).path.strip(\"/\").split(\"/\")[:-1]) for p in paths)\n if len(parents) > 1:\n duplicates.append({\"slug\": slug, \"urls\": paths})\n return duplicates\n\n\n# ─── Sitemap Parser ──────────────────────────────────────────────────────────\n\ndef parse_sitemap(content: str) -> list:\n \"\"\"Parse sitemap XML and return list of URL dicts.\"\"\"\n urls = []\n\n # Strip namespace declarations for simpler parsing\n content_clean = re.sub(r'xmlns[^=]*=\"[^\"]*\"', '', content)\n\n try:\n root = ET.fromstring(content_clean)\n except ET.ParseError as e:\n print(f\"❌ XML parse error: {e}\", file=sys.stderr)\n return []\n\n # Handle sitemap index (points to other sitemaps)\n if root.tag.endswith(\"sitemapindex\") or root.tag == \"sitemapindex\":\n print(\"ℹ️ This is a sitemap index file — it points to child sitemaps.\")\n print(\" Child sitemaps:\")\n for sitemap in root.findall(\".//{http://www.sitemaps.org/schemas/sitemap/0.9}loc\") or root.findall(\".//loc\"):\n print(f\" - {sitemap.text}\")\n print(\" Run this tool on each child sitemap for full analysis.\")\n return []\n\n # Regular urlset\n for url_el in root.findall(\".//{http://www.sitemaps.org/schemas/sitemap/0.9}url\") or root.findall(\".//url\"):\n loc_el = url_el.find(\"{http://www.sitemaps.org/schemas/sitemap/0.9}loc\") or url_el.find(\"loc\")\n lastmod_el = url_el.find(\"{http://www.sitemaps.org/schemas/sitemap/0.9}lastmod\") or url_el.find(\"lastmod\")\n priority_el = url_el.find(\"{http://www.sitemaps.org/schemas/sitemap/0.9}priority\") or url_el.find(\"priority\")\n\n if loc_el is not None and loc_el.text:\n urls.append({\n \"url\": loc_el.text.strip(),\n \"lastmod\": lastmod_el.text.strip() if lastmod_el is not None and lastmod_el.text else None,\n \"priority\": float(priority_el.text.strip()) if priority_el is not None and priority_el.text else None,\n })\n\n return urls\n\n\n# ─── Analysis Engine ─────────────────────────────────────────────────────────\n\ndef analyze_urls(urls: list) -> dict:\n raw_urls = [u[\"url\"] for u in urls]\n paths = [urlparse(u).path for u in raw_urls]\n\n depths = [get_depth(p) for p in paths]\n depth_counter = Counter(depths)\n\n dynamic_urls = [u for u in raw_urls if looks_like_dynamic_url(u)]\n\n patterns = Counter(get_path_pattern(urlparse(u).path) for u in raw_urls)\n top_patterns = patterns.most_common(10)\n\n duplicate_slugs = detect_path_siblings(raw_urls)\n\n deep_urls = [(u, get_depth(urlparse(u).path)) for u in raw_urls if get_depth(urlparse(u).path) >= 4]\n\n # Extract top-level directories\n top_dirs = Counter()\n for p in paths:\n parts = p.strip(\"/\").split(\"/\")\n if parts and parts[0]:\n top_dirs[parts[0]] += 1\n\n return {\n \"total_urls\": len(urls),\n \"depth_distribution\": dict(sorted(depth_counter.items())),\n \"top_directories\": dict(top_dirs.most_common(15)),\n \"dynamic_urls\": dynamic_urls,\n \"deep_pages\": deep_urls,\n \"duplicate_slug_candidates\": duplicate_slugs,\n \"top_url_patterns\": [{\"pattern\": p, \"count\": c} for p, c in top_patterns],\n }\n\n\n# ─── Report Printer ──────────────────────────────────────────────────────────\n\ndef grade_depth_distribution(dist: dict) -> str:\n deep = sum(v for k, v in dist.items() if k >= 4)\n total = sum(dist.values())\n if total == 0:\n return \"N/A\"\n pct = deep / total * 100\n if pct \u003c 5:\n return \"🟢 Excellent\"\n if pct \u003c 15:\n return \"🟡 Acceptable\"\n return \"🔴 Too many deep pages\"\n\n\ndef print_report(analysis: dict) -> None:\n print(\"\\n\" + \"═\" * 62)\n print(\" SITEMAP STRUCTURE ANALYSIS\")\n print(\"═\" * 62)\n print(f\"\\n Total URLs: {analysis['total_urls']}\")\n\n print(\"\\n── Depth Distribution ──\")\n dist = analysis[\"depth_distribution\"]\n total = analysis[\"total_urls\"]\n for depth, count in sorted(dist.items()):\n pct = count / total * 100 if total else 0\n bar = \"█\" * int(pct / 2)\n label = \"homepage\" if depth == 0 else f\"{' ' * min(depth, 3)}/{'…/' * (depth - 1)}page\"\n print(f\" Depth {depth}: {count:4d} pages ({pct:5.1f}%) {bar} {label}\")\n\n print(f\"\\n Rating: {grade_depth_distribution(dist)}\")\n deep_pct = sum(v for k, v in dist.items() if k >= 4) / total * 100 if total else 0\n if deep_pct >= 5:\n print(\" ⚠️ More than 5% of pages are 4+ levels deep.\")\n print(\" Consider flattening structure or adding shortcut links.\")\n\n print(\"\\n── Top-Level Directories ──\")\n for d, count in analysis[\"top_directories\"].items():\n pct = count / total * 100 if total else 0\n print(f\" /{d:\u003c30s} {count:4d} URLs ({pct:.1f}%)\")\n\n print(\"\\n── URL Pattern Analysis ──\")\n for p in analysis[\"top_url_patterns\"]:\n print(f\" {p['pattern']:\u003c45s} {p['count']:4d} URLs\")\n\n if analysis[\"dynamic_urls\"]:\n print(f\"\\n── Dynamic URLs Detected ({len(analysis['dynamic_urls'])}) ──\")\n print(\" ⚠️ URLs with query parameters should usually be excluded from sitemap.\")\n print(\" Use canonical tags or robots.txt to prevent duplicate content indexing.\")\n for u in analysis[\"dynamic_urls\"][:5]:\n print(f\" {u}\")\n if len(analysis[\"dynamic_urls\"]) > 5:\n print(f\" ... and {len(analysis['dynamic_urls']) - 5} more\")\n\n if analysis[\"deep_pages\"]:\n print(f\"\\n── Deep Pages (4+ Levels) ({len(analysis['deep_pages'])}) ──\")\n print(\" ⚠️ Pages this deep may have weak crawl equity. Add internal shortcuts.\")\n for url, depth in analysis[\"deep_pages\"][:5]:\n print(f\" Depth {depth}: {url}\")\n if len(analysis[\"deep_pages\"]) > 5:\n print(f\" ... and {len(analysis['deep_pages']) - 5} more\")\n\n if analysis[\"duplicate_slug_candidates\"]:\n print(f\"\\n── Potential Duplicate Path Issues ({len(analysis['duplicate_slug_candidates'])}) ──\")\n print(\" ⚠️ Same slug appears in multiple directories — possible duplicate content.\")\n for item in analysis[\"duplicate_slug_candidates\"][:5]:\n print(f\" Slug: '{item['slug']}'\")\n for u in item[\"urls\"]:\n print(f\" - {u}\")\n if len(analysis[\"duplicate_slug_candidates\"]) > 5:\n print(f\" ... and {len(analysis['duplicate_slug_candidates']) - 5} more\")\n\n print(\"\\n── Recommendations ──\")\n has_issues = False\n if analysis[\"dynamic_urls\"]:\n print(\" 1. Remove dynamic URLs (with ?) from sitemap.\")\n has_issues = True\n if analysis[\"deep_pages\"]:\n print(f\" {'2' if has_issues else '1'}. Flatten deep URL structures or add internal shortcut links.\")\n has_issues = True\n if analysis[\"duplicate_slug_candidates\"]:\n print(f\" {'3' if has_issues else '1'}. Review duplicate slug paths — consolidate or add canonical tags.\")\n has_issues = True\n if not has_issues:\n print(\" ✅ No major structural issues detected in this sitemap.\")\n\n print(\"\\n\" + \"═\" * 62)\n\n\n# ─── Main ─────────────────────────────────────────────────────────────────────\n\ndef load_content(source: str) -> str:\n \"\"\"Load sitemap from file path, URL, or stdin.\"\"\"\n if source.startswith(\"http://\") or source.startswith(\"https://\"):\n try:\n with urllib.request.urlopen(source, timeout=10) as resp: # noqa: SEC-AUDITOR (fetches only the URL the user passes, by design)\n return resp.read().decode(\"utf-8\")\n except urllib.error.URLError as e:\n print(f\"Error fetching URL: {e}\", file=sys.stderr)\n sys.exit(1)\n else:\n try:\n with open(source, \"r\", encoding=\"utf-8\") as f:\n return f.read()\n except FileNotFoundError:\n print(f\"Error: File not found: {source}\", file=sys.stderr)\n sys.exit(1)\n\n\ndef main():\n import argparse\n\n parser = argparse.ArgumentParser(\n description=\"Analyzes sitemap.xml files for structure, depth, and potential issues. \"\n \"Reports depth distribution, URL patterns, orphan candidates, and duplicates.\"\n )\n parser.add_argument(\n \"file\", nargs=\"?\", default=None,\n help=\"Path to a sitemap.xml file or URL (https://...). \"\n \"Use '-' to read from stdin. If omitted, runs embedded sample.\"\n )\n args = parser.parse_args()\n\n if args.file:\n if args.file == \"-\":\n content = sys.stdin.read()\n else:\n content = load_content(args.file)\n else:\n print(\"No file or URL provided — running on embedded sample sitemap.\\n\")\n content = SAMPLE_SITEMAP\n\n urls = parse_sitemap(content)\n if not urls:\n print(\"No URLs found in sitemap.\", file=sys.stderr)\n sys.exit(1)\n\n analysis = analyze_urls(urls)\n print_report(analysis)\n\n # JSON output\n print(\"\\n── JSON Summary ──\")\n summary = {\n \"total_urls\": analysis[\"total_urls\"],\n \"depth_distribution\": analysis[\"depth_distribution\"],\n \"dynamic_url_count\": len(analysis[\"dynamic_urls\"]),\n \"deep_page_count\": len(analysis[\"deep_pages\"]),\n \"duplicate_slug_count\": len(analysis[\"duplicate_slug_candidates\"]),\n \"top_directories\": analysis[\"top_directories\"],\n }\n print(json.dumps(summary, indent=2))\n\n\nif __name__ == \"__main__\":\n main()\n","content_type":"text/x-python; charset=utf-8","language":"python","size":15233,"content_sha256":"398e0c8cf1d74a16520f0e5038205346f9457aa7b2bc36e2356d580327b09227"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Site Architecture & Internal Linking","type":"text"}]},{"type":"paragraph","content":[{"text":"You are an expert in website information architecture and technical SEO structure. Your goal is to design website architecture that makes it easy for users to navigate, easy for search engines to crawl, and builds topical authority through intelligent internal linking.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Before Starting","type":"text"}]},{"type":"paragraph","content":[{"text":"Check for context first:","type":"text","marks":[{"type":"strong"}]},{"text":" If ","type":"text"},{"text":".claude/product-marketing-context.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists, read it before asking questions.","type":"text"}]},{"type":"paragraph","content":[{"text":"Gather this context:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"1. Current State","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do they have an existing site? (URL, CMS, sitemap.xml available?)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"How many pages exist? Rough estimate by section.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What are the top-performing pages (if they know)?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Any known problems: orphan pages, duplicate content, poor rankings?","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"2. Goals","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Primary business goal (lead gen, e-commerce, content authority, local search)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Target audience and their mental model of navigation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Specific SEO targets — topics or keyword clusters they want to rank for","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"3. Constraints","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CMS capabilities (can they change URLs? Does it auto-generate certain structures?)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Redirect capacity (if restructuring, can they manage bulk 301s?)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Development resources (minor tweaks vs full migration)","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"How This Skill Works","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Mode 1: Audit Current Architecture","type":"text"}]},{"type":"paragraph","content":[{"text":"When a site exists and they need a structural assessment.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"scripts/sitemap_analyzer.py","type":"text","marks":[{"type":"code_inline"}]},{"text":" on their sitemap.xml (or paste sitemap content)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review: depth distribution, URL patterns, potential orphans, duplicate paths","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Evaluate navigation by reviewing the site manually or from their description","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify the top structural problems by SEO impact","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deliver a prioritized audit with quick wins and structural recommendations","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Mode 2: Plan New Structure","type":"text"}]},{"type":"paragraph","content":[{"text":"When building a new site or doing a full redesign/restructure.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Map business goals to site sections","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Design URL hierarchy (flat vs layered by content type)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Define content silos for topical authority","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Plan navigation zones: primary nav, breadcrumbs, footer nav, contextual","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deliver site map diagram (text-based tree) + URL structure spec","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Mode 3: Internal Linking Strategy","type":"text"}]},{"type":"paragraph","content":[{"text":"When the structure is fine but they need to improve link equity flow and topical signals.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify hub pages (the pillar content that should rank highest)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Map spoke pages (supporting content that links to hubs)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Find orphan pages (indexed pages with no inbound internal links)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify anchor text patterns and over-optimized phrases","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deliver an internal linking plan: which pages link to which, with anchor text guidance","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"URL Structure Principles","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"The Core Rule: URLs are for Humans First","type":"text"}]},{"type":"paragraph","content":[{"text":"A URL should tell a user exactly where they are before they click. It also tells search engines about content hierarchy. Get this right once — URL changes later require redirects and lose equity.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Flat vs Layered: Pick the Right Depth","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Depth","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Example","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use When","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Flat (1 level)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/blog/cold-email-tips","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Blog posts, articles, standalone pages","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Two levels","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/blog/email-marketing/cold-email-tips","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When category is a ranking page itself","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Three levels","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/solutions/marketing/email-automation","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Product families, nested services","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"4+ levels","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/a/b/c/d/page","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"❌ Avoid — dilutes crawl equity, confusing","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Rule of thumb:","type":"text","marks":[{"type":"strong"}]},{"text":" If the category URL (","type":"text"},{"text":"/blog/email-marketing/","type":"text","marks":[{"type":"code_inline"}]},{"text":") is not a real page you want to rank, don't create the directory. Flat is usually better for SEO.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"URL Construction Rules","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Do","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Don't","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/how-to-write-cold-emails","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/how_to_write_cold_emails","type":"text","marks":[{"type":"code_inline"}]},{"text":" (underscores)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/pricing","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/pricing-page","type":"text","marks":[{"type":"code_inline"}]},{"text":" (redundant suffixes)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/blog/seo-tips-2024","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/blog/article?id=4827","type":"text","marks":[{"type":"code_inline"}]},{"text":" (dynamic, non-descriptive)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/services/web-design","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/services/web-design/","type":"text","marks":[{"type":"code_inline"}]},{"text":" (trailing slash — pick one and be consistent)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/about","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/about-us-company-info","type":"text","marks":[{"type":"code_inline"}]},{"text":" (keyword stuffing the URL)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Short, human-readable","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Long, generated, token-filled","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Keywords in URLs","type":"text"}]},{"type":"paragraph","content":[{"text":"Yes — include the primary keyword. No — don't stuff 4 keywords in.","type":"text"}]},{"type":"paragraph","content":[{"text":"/guides/technical-seo-audit","type":"text","marks":[{"type":"code_inline"}]},{"text":" ✅ ","type":"text"},{"text":"/guides/technical-seo-audit-checklist-how-to-complete-step-by-step","type":"text","marks":[{"type":"code_inline"}]},{"text":" ❌","type":"text"}]},{"type":"paragraph","content":[{"text":"The keyword in the URL is a minor signal, not a major one. Don't sacrifice readability for it.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Reference docs","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/url-design-guide.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for patterns by site type (blog, SaaS, e-commerce, local).","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Navigation Design","type":"text"}]},{"type":"paragraph","content":[{"text":"Navigation serves two masters: user experience and link equity flow. Most sites optimize for neither.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Navigation Zones","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Zone","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SEO Role","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Primary nav","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Core site sections, 5-8 items max","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Passes equity to top-level pages","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Secondary nav","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Sub-sections within a section","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Passes equity within a silo","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Breadcrumbs","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Current location in hierarchy","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Equity from deep pages upward","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Footer nav","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Secondary utility links, key service pages","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Sitewide links — use carefully","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Contextual nav","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"In-content links, related posts, \"next step\" links","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Most powerful equity signal","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Sidebar","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Related content, category listing","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Medium equity if above fold","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Primary Navigation Rules","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"5-8 items maximum. Cognitive load increases with every item.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each nav item should link to a page you want to rank.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Never use nav labels like \"Resources\" with no landing page — it should be a real, rankable resources page.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Dropdown menus are fine but crawlers may not engage them deeply — critical pages need a clickable parent link.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Breadcrumbs","type":"text"}]},{"type":"paragraph","content":[{"text":"Add breadcrumbs to every non-homepage page. They do three things:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Show users where they are","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create site-wide upward internal links to category/hub pages","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Enable BreadcrumbList schema for rich results in Google","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Format: ","type":"text"},{"text":"Home > Category > Subcategory > Current Page","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Every breadcrumb segment should be a real, crawlable link — not just styled text.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Silo Structure & Topical Authority","type":"text"}]},{"type":"paragraph","content":[{"text":"A silo is a self-contained cluster of content about one topic, where all pages link to each other and to a central hub page. Google uses this to determine topical authority.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Hub-and-Spoke Model","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"HUB: /seo/ ← Pillar page, broad topic\n SPOKE: /seo/technical-seo/ ← Sub-topic\n SPOKE: /seo/on-page-seo/ ← Sub-topic\n SPOKE: /seo/link-building/ ← Sub-topic\n SPOKE: /seo/keyword-research/ ← Sub-topic\n └─ DEEP: /seo/keyword-research/long-tail-keywords/ ← Specific guide","type":"text"}]},{"type":"paragraph","content":[{"text":"Linking rules within a silo:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hub links to all spokes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each spoke links back to hub","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Spokes can link to adjacent spokes (contextually relevant)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deep pages link up to their spoke + the hub","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cross-silo links are fine when genuinely relevant — just don't build a link for its own sake","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Building Topic Clusters","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify your core topics (usually 3-7 for a focused site)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each topic: one pillar page (the hub) that covers it broadly","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create spoke content for each major sub-question within the topic","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every spoke links to the pillar with relevant anchor text","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The pillar links down to all spokes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build the cluster before you build the links — if you don't have the content, the links don't help","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Internal Linking Strategy","type":"text"}]},{"type":"paragraph","content":[{"text":"Internal links are the most underused SEO lever. They're fully under your control, free, and directly affect which pages rank.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Link Equity Principles","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Google crawls your site from the homepage outward","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pages closer to the homepage (fewer clicks away) get more equity","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A page with no internal links is an orphan — Google won't prioritize it","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Anchor text matters: generic (\"click here\") signals nothing; descriptive (\"cold email templates\") signals topic relevance","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Anchor Text Rules","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Type","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Example","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Exact match","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"cold email templates\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use sparingly — 1-2x per page, looks natural","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Partial match","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"writing effective cold emails\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Primary approach — most internal links","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Branded","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"our email guide\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fine, not the most powerful","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Generic","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"click here\", \"learn more\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Avoid — wastes the signal","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Naked URL","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"https://example.com/guide","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Never use for internal links","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Finding and Fixing Orphan Pages","type":"text"}]},{"type":"paragraph","content":[{"text":"An orphan page is indexed but has no inbound internal links. It's invisible to the site's link graph.","type":"text"}]},{"type":"paragraph","content":[{"text":"How to find them:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Export all indexed URLs (from GSC, Screaming Frog, or ","type":"text"},{"text":"sitemap_analyzer.py","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Export all internal links on the site","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pages that appear in set A but not set B are orphans","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Or: run ","type":"text"},{"text":"scripts/sitemap_analyzer.py","type":"text","marks":[{"type":"code_inline"}]},{"text":" which flags potential orphan candidates","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"How to fix them:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add contextual links from relevant existing pages","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add them to relevant hub pages","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If they truly have no home, consider whether they should exist at all","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"The Linking Priority Stack","type":"text"}]},{"type":"paragraph","content":[{"text":"Not all internal links are equal. From most to least powerful:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"In-content links","type":"text","marks":[{"type":"strong"}]},{"text":" — within the body copy of a relevant page. Most natural, most powerful.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hub page links","type":"text","marks":[{"type":"strong"}]},{"text":" — the pillar page linking to all its spokes. High equity because pillar pages are linked from everywhere.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Navigation links","type":"text","marks":[{"type":"strong"}]},{"text":" — sitewide, consistent, but diluted by their ubiquity.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Footer links","type":"text","marks":[{"type":"strong"}]},{"text":" — sitewide, but Google gives them less weight than in-content.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Sidebar links","type":"text","marks":[{"type":"strong"}]},{"text":" — OK but often not in the main content flow.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/internal-linking-playbook.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for patterns and scripts.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Common Architecture Mistakes","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mistake","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Why It Hurts","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fix","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Orphan pages","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No equity flows in, Google deprioritizes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Add contextual internal links from related content","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"URL changes without redirects","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Inbound links become broken, equity lost","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Always 301 redirect old URLs to new ones","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Duplicate paths","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"/blog/seo","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"/resources/seo","type":"text","marks":[{"type":"code_inline"}]},{"text":" covering same topic","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Consolidate with canonical or merge content","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Deep nesting (4+ levels)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Crawl equity diluted, users confused","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Flatten structure, remove unnecessary directories","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Sitewide footer links to every post","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Footer equity is diluted across 500 links","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Footer should link to high-value pages only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Navigation that doesn't match user intent","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Users leave, rankings drop","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Run card-sort tests — let users show you their mental model","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Homepage linking nowhere","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Home is highest-equity page — use it","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Link from home to key hub pages","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Category pages with no content","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Thin pages rank poorly","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Add content to all hub/category pages","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Dynamic URLs with parameters","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"?sort=&filter=","type":"text","marks":[{"type":"code_inline"}]},{"text":" creates duplicate content","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Canonicalize or block with robots.txt","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Proactive Triggers","type":"text"}]},{"type":"paragraph","content":[{"text":"Surface these without being asked:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pages more than 3 clicks from homepage","type":"text","marks":[{"type":"strong"}]},{"text":" → flag as crawl equity risk. Any page a user has to click 4+ times to reach needs a structural shortcut.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Category/hub page has thin or no content","type":"text","marks":[{"type":"strong"}]},{"text":" → hub pages without real content don't rank. Flag and recommend adding a proper pillar page.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Internal links using generic anchor text (\"click here\", \"read more\")","type":"text","marks":[{"type":"strong"}]},{"text":" → wasted signal. Offer to rewrite anchor text patterns.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No breadcrumbs on deep pages","type":"text","marks":[{"type":"strong"}]},{"text":" → missing upward equity links and BreadcrumbList schema opportunity.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Sitemap includes noindex pages","type":"text","marks":[{"type":"strong"}]},{"text":" → sitemap should only contain pages you want indexed. Flag and offer to filter.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Primary nav links to utility pages (contact, privacy)","type":"text","marks":[{"type":"strong"}]},{"text":" → pushing equity to low-value pages. Nav should prioritize money/content pages.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output Artifacts","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When you ask for...","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"You get...","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Architecture audit","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Structural scorecard: depth distribution, orphan count, URL pattern issues, navigation gaps + prioritized fix list","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"New site structure","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Text-based site tree (hierarchy diagram) + URL spec table with notes per section","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Internal linking plan","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Hub-and-spoke map per topic cluster + anchor text guidelines + orphan fix list","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"URL redesign","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Before/after URL table + 301 redirect mapping + implementation checklist","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Silo strategy","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Topic cluster map per business goal + content gap analysis + pillar page brief","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Communication","type":"text"}]},{"type":"paragraph","content":[{"text":"All output follows the structured communication standard:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Bottom line first","type":"text","marks":[{"type":"strong"}]},{"text":" — answer before explanation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What + Why + How","type":"text","marks":[{"type":"strong"}]},{"text":" — every finding has all three","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Actions have owners and deadlines","type":"text","marks":[{"type":"strong"}]},{"text":" — no \"we should consider\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confidence tagging","type":"text","marks":[{"type":"strong"}]},{"text":" — 🟢 verified / 🟡 medium / 🔴 assumed","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Related Skills","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"seo-audit","type":"text","marks":[{"type":"strong"}]},{"text":": For comprehensive SEO audit covering technical, on-page, and off-page. Use seo-audit when architecture is one of several problem areas. NOT for deep structural redesign — use site-architecture.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"schema-markup","type":"text","marks":[{"type":"strong"}]},{"text":": For structured data implementation. Use after site-architecture when you want to add BreadcrumbList and other schema to your finalized structure.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"content-strategy","type":"text","marks":[{"type":"strong"}]},{"text":": For deciding what content to create. Use content-strategy to plan the content, then site-architecture to determine where it lives and how it links.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"programmatic-seo","type":"text","marks":[{"type":"strong"}]},{"text":": When you need to generate hundreds or thousands of pages systematically. Site-architecture provides the URL and structural patterns that programmatic-seo scales.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"seo-audit","type":"text","marks":[{"type":"strong"}]},{"text":": For identifying technical issues. NOT for architecture redesign planning — use site-architecture for that.","type":"text"}]}]}]}]},"metadata":{"date":"2026-11-02","name":"site-architecture","author":"@skillopedia","source":{"stars":29164,"repo_name":"claude-skills","origin_url":"https://github.com/alirezarezvani/claude-skills/blob/HEAD/marketing-skill/skills/site-architecture/SKILL.md","repo_owner":"alirezarezvani","body_sha256":"a1db34c74ed863b8049d4e5672a607ff2da2d5caf1d9dda16076e33e2fea840d","cluster_key":"6957f54afe8c9f8a77cd27c0cb33a86848ec44195f8e1b27146d860e5a10d43b","clean_bundle":{"format":"clean-skill-bundle-v1","source":"alirezarezvani/claude-skills/marketing-skill/skills/site-architecture/SKILL.md","text_bytes":32389,"source_commit":"9ef0c3c213932e645cc5cbeeb3c35c3a762a2437","skills_sh_rank":17165,"attachment_count":3,"text_attachments":3,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"marketing-skill/skills/site-architecture/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"web-development","category_label":"Web"},"exact_dupes_collapsed_into_this":0},"license":"MIT","version":"v1","category":"web-development","metadata":{"author":"Alireza Rezvani","updated":"2026-03-06T00:00:00.000Z","version":"1.0.0","category":"marketing"},"import_tag":"skills-sh-top20k-2026-11","description":"Use for URL structure, navigation, internal linking, hub pages or orphan pages, or when SEO problems are structural. Analyzes the sitemap and link graph with sitemap_analyzer.py before proposing a structure."}},"renderedAt":1793671839160}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.