version: "1.0.1" name: pseo-linking description: Build an intelligent internal linking system using hub-and-spoke structures, related page suggestions, breadcrumb navigation, and topical clustering for programmatic SEO. Use when implementing or improving internal linking, adding breadcrumbs, building category hub pages, or creating related-pages components. argument-hint: "[component: all | breadcrumbs | related | hubs | sitemap]" allowed-tools: Read, Glob, Grep, Bash, Edit, Write

pSEO Internal Linking

Build an internal linking system that creates strong topical authority, distributes link equity, and ensures every page is discoverable.

Core Principles

1. Hub-and-spoke architecture: Category hubs link to all child pages; child pages link back to their hub
2. Topical clustering: Pages within the same topic cluster interlink
3. Every page reachable: No orphan pages — every page is linked from at least 2 other pages
4. Crawl depth <= 3: Any page reachable within 3 clicks from the homepage
5. Descriptive anchor text: Link text describes the target page, not generic "click here"

Architecture

Homepage
├── Category Hub A ──→ Page A1, A2, A3, ...
│   ├── Page A1 ──→ Hub A, A2, A3 (related)
│   ├── Page A2 ──→ Hub A, A1, A3 (related)
│   └── Page A3 ──→ Hub A, A1, A2 (related)
├── Category Hub B ──→ Page B1, B2, B3, ...
│   └── ...
└── Sitemap (links all hubs)

Implementation Steps

1. Breadcrumb Navigation

Build a breadcrumb component that:

• Renders the full path: Home > Category > Current Page
• Uses semantic HTML (<nav> with <ol>)
• Generates BreadcrumbList schema markup (coordinate with pseo-schema)
• Appears on every pSEO page

interface BreadcrumbItem {
  label: string;
  href: string;
}
function Breadcrumbs({ items }: { items: BreadcrumbItem[] }) {
  return (
    <nav aria-label="Breadcrumb">
      <ol>
        {items.map((item, i) => (
          <li key={item.href}>
            {i < items.length - 1 ? (
              <a href={item.href}>{item.label}</a>
            ) : (
              <span aria-current="page">{item.label}</span>
            )}
          </li>
        ))}
      </ol>
    </nav>
  );
}

2. Related Pages Component

Build a component that displays links to related pages:

• Pull related pages from the data layer's getRelatedPages(slug, limit) function
• Show 3-6 related pages per page
• Prioritize pages in the same category, then adjacent categories
• Use the page's H1 or title as anchor text
• Include a brief description or differentiator for each link

Relatedness signals (in priority order):

1. Same category
2. Shared tags or attributes
3. Similar content type
4. Alphabetically adjacent (fallback)

3. Hub Pages (Category Landing Pages)

Hub page creation is owned by pseo-templates (section 7). From a linking perspective, ensure every hub page:

• Links to all child pages in the category (or paginates if >50)
• Is linked from the homepage or global navigation
• Has CollectionPage or ItemList schema markup (coordinate with pseo-schema)

4. Cross-Category Linking

Identify and implement cross-category linking opportunities:

• "See also" sections linking to related pages in other categories
• Comparison pages that bridge categories
• Tag-based linking (pages sharing the same tag link to each other)

5. Footer/Sidebar Navigation

Add persistent navigation that links to:

• All category hub pages
• Most popular or cornerstone content pages
• This ensures hubs are reachable from every page (crawl depth = 2)

6. XML Sitemap

Generate a dynamic sitemap that:

• Includes all pSEO pages with lastmod dates
• Groups URLs by category using sitemap index
• Updates automatically when pages are added
• Handles 1000+ URLs (split into multiple sitemaps at 50,000 limit)

// app/sitemap.ts (Next.js App Router)
export default async function sitemap() {
  const categories = await getAllCategories();
  const entries = [];
  // Hub pages (higher priority)
  for (const cat of categories) {
    entries.push({
      url: `${baseUrl}/${cat.slug}`,
      lastModified: cat.lastModified,
      changeFrequency: "weekly" as const,
      priority: 0.8,
    });
  }
  // Child pages (PageIndex has lastModified)
  for (const cat of categories) {
    const pages = await getPagesByCategory(cat.slug);
    for (const page of pages) {
      entries.push({
        url: `${baseUrl}/${cat.slug}/${page.slug}`,
        lastModified: page.lastModified,
        changeFrequency: "weekly" as const,
        priority: 0.6,
      });
    }
  }
  return entries;
}

7. Redirect Management

At 1000+ pages, slug and URL changes are inevitable. Build a redirect system:

• Maintain a redirect map (JSON file, database table, or framework config) that maps old paths to new paths
• All redirects must be 301 (permanent) to preserve link equity
• When a slug changes, automatically add the old URL to the redirect map
• When a category is renamed, redirect all child URLs under the old category path
• Implement a redirect middleware or config that processes the map on every request
• Validate: no redirect chains (A → B → C), no redirect loops, no redirects to 404s

Next.js pattern:

// next.config.js
async redirects() {
  const map = await loadRedirectMap();
  return map.map(({ source, destination }) => ({
    source,
    destination,
    permanent: true,
  }));
}

Build-time validation:

• All redirect sources must not match any current live slug
• All redirect destinations must resolve to a live page
• Log warnings for redirects older than 12 months (consider removing)

8. robots.txt and AI Crawler Access

Create or update robots.txt to:

• Allow all pSEO pages for traditional crawlers (Googlebot, Bingbot)
• Allow AI retrieval crawlers needed for LLM citation (GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot)
• Optionally block AI training crawlers (Google-Extended, CCBot)
• Reference both the sitemap and llms.txt
• Block utility/admin pages

Critical: Blocking Bingbot or GPTBot means zero visibility in ChatGPT. See pseo-llm-visibility for full AI crawler configuration.

9. llms.txt

llms.txt creation is owned by pseo-llm-visibility (section 1). From a linking perspective, ensure llms.txt references all category hub pages and the sitemap. The robots.txt should include a comment pointing to llms.txt.

Link Health Checks

Verify:

• [ ] No orphan pages (every page linked from at least 2 others)
• [ ] Hub pages link to all their child pages
• [ ] Child pages link back to their hub
• [ ] Breadcrumbs are present on every page
• [ ] Related pages section shows 3-6 links
• [ ] No broken internal links (all hrefs resolve to 200)
• [ ] Sitemap includes all public pages
• [ ] Crawl depth from homepage <= 3 for any page
• [ ] Redirect map exists and covers all historical URL changes
• [ ] No redirect chains or loops
• [ ] All redirect destinations resolve to live pages
• [ ] robots.txt allows AI retrieval crawlers (GPTBot, PerplexityBot, ClaudeBot, Bingbot)
• [ ] llms.txt exists at site root with category hubs and page type descriptions

Relationship to Other Skills

• Depends on: pseo-data (category data, related page queries)
• Provides to: pseo-schema (breadcrumb items for BreadcrumbList schema)
• Works with: pseo-templates (linking components are rendered in templates)