Internal Linking Automation for pSEO

Automated internal linking is the connective tissue of a pSEO site. Without it, thousands of pages exist in isolation - hard for Google to crawl and impossible to pass PageRank between. With it, the cluster becomes a topical authority signal.

Hub-and-spoke architecture

The fundamental pSEO link structure. A small number of "hub" pages (high editorial value, strong links) fan out to many "spoke" pages (programmatic, data-driven).

                    ┌─────────────────┐
                    │   Root Hub      │
                    │  /accountants/  │
                    └────────┬────────┘
                             │
           ┌─────────────────┼──────────────────┐
           │                 │                  │
    ┌──────▼──────┐  ┌───────▼──────┐  ┌───────▼──────┐
    │  State Hub  │  │  State Hub   │  │  State Hub   │
    │  /TX/       │  │  /CA/        │  │  /NY/        │
    └──────┬──────┘  └──────────────┘  └──────────────┘
           │
    ┌──────┴──────────────────────────────────┐
    │        │           │          │         │
  Austin   Dallas    Houston    San Antonio  Austin
  spoke    spoke     spoke      spoke        spoke

Link direction rules:

• Hubs always link DOWN to spokes (navigational breadth)
• Spokes always link UP to their hub (authority concentration)
• Spokes link SIDEWAYS to nearby spokes (topical clustering)
• Never link from spoke to spoke across different hubs without context

Related pages algorithm

The algorithm that decides which pages link to each other on the same level.

Geographic proximity (location pSEO)

// lib/related-pages/geographic.ts
import { db } from '@/lib/db';

interface RelatedPage {
  title: string;
  href: string;
  signal: string; // "120 providers" or "from $45/hr"
}

export async function getGeographicRelatedPages(
  citySlug: string,
  stateSlug: string,
  serviceSlug: string,
  limit = 6
): Promise<RelatedPage[]> {
  // Priority 1: same state, same service (most relevant)
  const sameSate = await db.locationPages.findMany({
    where: {
      stateSlug,
      serviceSlug,
      citySlug: { not: citySlug },
      qualityScore: { gte: 65 },
    },
    orderBy: { providerCount: 'desc' }, // show richest pages first
    take: limit,
  });

  if (sameSate.length >= limit) {
    return sameSate.map(toRelatedPage);
  }

  // Priority 2: different state, same service (fill remaining slots)
  const otherStates = await db.locationPages.findMany({
    where: {
      serviceSlug,
      stateSlug: { not: stateSlug },
      citySlug: { not: citySlug },
      qualityScore: { gte: 65 },
    },
    orderBy: { searchVolume: 'desc' },
    take: limit - sameSate.length,
  });

  return [...sameSate, ...otherStates].map(toRelatedPage);
}

function toRelatedPage(loc: {
  cityName: string;
  citySlug: string;
  serviceSlug: string;
  providerCount: number;
}): RelatedPage {
  return {
    title: `${loc.cityName}`,
    href: `/${loc.serviceSlug}/${loc.citySlug}`,
    signal: `${loc.providerCount} providers`,
  };
}

Categorical similarity (comparison/tool pSEO)

// lib/related-pages/categorical.ts

export async function getCategoricalRelatedPages(
  currentSlug: string,
  categoryTags: string[],
  limit = 6
): Promise<RelatedPage[]> {
  // Find pages sharing the most tags with the current page
  const candidates = await db.comparisonPages.findMany({
    where: {
      slug: { not: currentSlug },
      tags: { hasSome: categoryTags },
      qualityScore: { gte: 65 },
    },
  });

  // Score by tag overlap count
  const scored = candidates
    .map((page) => ({
      page,
      overlap: page.tags.filter((t) => categoryTags.includes(t)).length,
    }))
    .sort((a, b) => b.overlap - a.overlap)
    .slice(0, limit);

  return scored.map(({ page }) => ({
    title: page.title,
    href: `/${page.slug}`,
    signal: page.shortSummary,
  }));
}

Breadcrumb generation

Breadcrumbs serve dual purpose: user navigation and internal linking to hub pages. Every breadcrumb link is an internal link with descriptive anchor text.

// lib/breadcrumbs.ts

export interface Breadcrumb {
  label: string;
  href: string | null; // null for the current page (no link)
}

export function buildLocationBreadcrumbs(
  serviceLabel: string,
  serviceSlug: string,
  stateLabel: string,
  stateSlug: string,
  cityLabel: string,
): Breadcrumb[] {
  return [
    { label: 'Home', href: '/' },
    { label: serviceLabel, href: `/${serviceSlug}/` },
    { label: stateLabel, href: `/${serviceSlug}/${stateSlug}/` },
    { label: cityLabel, href: null }, // current page - no link
  ];
}

// React component
// components/Breadcrumbs.tsx
import type { Breadcrumb } from '@/lib/breadcrumbs';

export function Breadcrumbs({ crumbs }: { crumbs: Breadcrumb[] }) {
  return (
    <nav aria-label="Breadcrumb">
      <ol itemScope itemType="https://schema.org/BreadcrumbList">
        {crumbs.map((crumb, index) => (
          <li
            key={crumb.label}
            itemScope
            itemType="https://schema.org/ListItem"
            itemProp="itemListElement"
          >
            {crumb.href ? (
              <a href={crumb.href} itemProp="item">
                <span itemProp="name">{crumb.label}</span>
              </a>
            ) : (
              <span itemProp="name">{crumb.label}</span>
            )}
            <meta itemProp="position" content={String(index + 1)} />
          </li>
        ))}
      </ol>
    </nav>
  );
}

Add BreadcrumbList schema markup to the breadcrumbs. Google uses this to display breadcrumb trails in SERPs, which improves click-through rate for pSEO pages.

Contextual link injection

Beyond a "related pages" section, inject links directly into body copy where relevant. This is the highest-value internal link type because anchor text is natural and in-context.

// lib/contextual-links.ts

interface ContextualLinkConfig {
  keyword: string;       // trigger phrase in body copy
  href: string;          // destination URL
  anchorText: string;    // anchor text to use (may differ from keyword)
  maxOccurrences: number; // how many times to inject per page (usually 1)
}

export function injectContextualLinks(
  htmlContent: string,
  links: ContextualLinkConfig[]
): string {
  let result = htmlContent;

  for (const link of links) {
    let count = 0;
    const regex = new RegExp(`\\b(${escapeRegex(link.keyword)})\\b`, 'gi');

    result = result.replace(regex, (match) => {
      if (count >= link.maxOccurrences) return match;
      count++;
      return `<a href="${link.href}">${link.anchorText}</a>`;
    });
  }

  return result;
}

function escapeRegex(str: string): string {
  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

// Usage in template rendering
const links: ContextualLinkConfig[] = await db.contextualLinks.findMany({
  where: { pageType: 'location', serviceSlug: data.serviceSlug },
});

const linkedContent = injectContextualLinks(data.bodyHtml, links);

Limit contextual injection to 1 occurrence per keyword per page. Over-linking looks spammy and can trigger Google's link spam classifier. One natural link outperforms three forced ones.

Silo architecture

A silo groups topically related pages so PageRank flows within the topic cluster rather than leaking to unrelated content.

Hard silo (strict): pages within a silo only link to other pages in the same silo. Used for highly competitive niches where topical authority concentration matters most.

Soft silo (practical): pages primarily link within their silo, but cross-silo links are allowed at the hub level. This is the recommended approach for most pSEO sites.

// lib/silo.ts - enforce soft silo rules

export function validateInternalLink(
  sourceSilo: string,
  targetSilo: string,
  sourceDepth: number,  // 0 = root, 1 = hub, 2 = spoke
): { allowed: boolean; reason?: string } {
  // Rule 1: same-silo links always allowed
  if (sourceSilo === targetSilo) {
    return { allowed: true };
  }

  // Rule 2: root and hub pages can cross-link (soft silo)
  if (sourceDepth <= 1) {
    return { allowed: true };
  }

  // Rule 3: spokes cannot cross-link to other silos
  return {
    allowed: false,
    reason: `Spoke page in silo "${sourceSilo}" cannot link to silo "${targetSilo}"`,
  };
}

URL structure reflects silo structure:

/accountants/                    ← root hub (silo: accountants)
/accountants/texas/              ← state hub
/accountants/texas/austin/       ← city spoke
/accountants/texas/dallas/       ← city spoke

/bookkeepers/                    ← separate silo
/bookkeepers/texas/
/bookkeepers/texas/austin/

Link graph visualization

For large pSEO sites, visualize the link graph to spot orphaned pages, thin clusters, and over-linked hub pages.

// scripts/generate-link-graph.ts
// Outputs a Graphviz DOT file for visualization

import { db } from '@/lib/db';

async function generateLinkGraph(): Promise<void> {
  const pages = await db.locationPages.findMany({
    include: { outboundLinks: { include: { target: true } } },
  });

  const lines: string[] = ['digraph pSEO {', '  rankdir=TB;'];

  for (const page of pages) {
    const depth = page.depth; // 0=root, 1=state, 2=city
    const color = depth === 0 ? 'red' : depth === 1 ? 'orange' : 'lightblue';
    lines.push(`  "${page.slug}" [label="${page.slug}" fillcolor="${color}" style=filled];`);

    for (const link of page.outboundLinks) {
      lines.push(`  "${page.slug}" -> "${link.target.slug}";`);
    }
  }

  lines.push('}');

  const fs = await import('fs');
  fs.writeFileSync('reports/link-graph.dot', lines.join('\n'));
  console.log('Link graph written to reports/link-graph.dot');
  console.log('Render: dot -Tsvg reports/link-graph.dot -o reports/link-graph.svg');
}

generateLinkGraph();

Metrics to check in the graph:

Link audit script

Run periodically to detect internal linking regressions - orphaned pages, broken links, or silo violations introduced during data updates.

// scripts/link-audit.ts
import { db } from '@/lib/db';

interface AuditResult {
  orphanedPages: string[];
  brokenLinks: Array<{ source: string; target: string }>;
  siloViolations: Array<{ source: string; target: string; reason: string }>;
}

export async function runLinkAudit(): Promise<AuditResult> {
  const allPages = await db.locationPages.findMany({
    include: { outboundLinks: true, inboundLinks: true },
  });

  const slugSet = new Set(allPages.map((p) => p.slug));

  const orphanedPages = allPages
    .filter((p) => p.depth > 0 && p.inboundLinks.length === 0)
    .map((p) => p.slug);

  const brokenLinks: AuditResult['brokenLinks'] = [];
  const siloViolations: AuditResult['siloViolations'] = [];

  for (const page of allPages) {
    for (const link of page.outboundLinks) {
      if (!slugSet.has(link.targetSlug)) {
        brokenLinks.push({ source: page.slug, target: link.targetSlug });
      }

      const target = allPages.find((p) => p.slug === link.targetSlug);
      if (target && page.depth >= 2 && page.silo !== target.silo) {
        siloViolations.push({
          source: page.slug,
          target: target.slug,
          reason: `Cross-silo spoke link: ${page.silo} -> ${target.silo}`,
        });
      }
    }
  }

  return { orphanedPages, brokenLinks, siloViolations };
}

// CI integration - fail build if audit finds regressions
const result = await runLinkAudit();
const issues = result.orphanedPages.length + result.brokenLinks.length + result.siloViolations.length;

if (issues > 0) {
  console.error('Link audit failed:', JSON.stringify(result, null, 2));
  process.exit(1);
}

console.log('Link audit passed. No issues found.');

Run this in CI before deploying any data update that adds, removes, or restructures pSEO pages. A broken internal link graph is silent in production but compounds over time as Google's crawl model of your site diverges from reality.

pSEO Template Generation

Deep reference for designing templates, sourcing data, generating pages at scale, and enforcing quality before publication.

Template anatomy

A pSEO template has three zones that must be explicitly designed:

┌─────────────────────────────────────────────┐
│  HEADER FORMULA (semi-unique)               │
│  H1: [Service] in [City], [State]           │
│  Meta: Best [Service] in [City] | [Brand]   │
├─────────────────────────────────────────────┤
│  UNIQUE DATA ZONES (per-page data)          │
│  ● Local statistics / market data           │
│  ● Provider list / inventory / prices       │
│  ● User reviews / ratings                  │
│  ● Comparison table rows                   │
├─────────────────────────────────────────────┤
│  SUPPORTING CONTENT (boilerplate)           │
│  ● How it works explanation                 │
│  ● FAQs (partially templatized)             │
│  ● Trust signals (partly unique)            │
├─────────────────────────────────────────────┤
│  INTERNAL LINKS (auto-generated)            │
│  ● Related pages sidebar/section            │
│  ● Breadcrumb navigation                   │
│  ● Hub page back-link                      │
├─────────────────────────────────────────────┤
│  CTA (boilerplate + personalized)           │
│  ● Primary action tied to page context      │
└─────────────────────────────────────────────┘

Header formula patterns:

Always include the year in title tags for pages where freshness is a ranking factor (comparison pages, top-N aggregators). Use a currentYear slot populated at build time - never hard-code.

Data sourcing strategies

Tier 1 - Proprietary / user-generated data (highest moat)

Data that only you have. Google cannot find this elsewhere, so pages are inherently unique.

• Product database: inventory, pricing, SKU attributes
• User reviews and ratings: collected via your platform
• Transaction data: average deal size, volume, completion rate
• Behavioral data: "most searched for in [city]" signals

Tier 2 - Licensed dataset APIs

Paid APIs where the license restricts redistribution. Other pSEO competitors cannot replicate your exact dataset.

• Yelp Fusion API - business listings, reviews, hours
• Google Places API - location data, ratings, photos
• Clearbit - company enrichment data for B2B pSEO
• SerpAPI - SERP data for comparison research pages
• Numerator / Nielsen - consumer market data (expensive, high moat)

Tier 3 - Aggregated public data (lowest moat)

Free and open data that anyone can use. Low moat but fast to get started.

• US Census Bureau - population, income, demographics by city
• BLS.gov - labor market data, wage data by metro
• Data.gov - government open datasets by topic
• Wikipedia data dumps - useful for glossary and entity pages
• OpenStreetMap - geographic data for location pages

Data freshness requirements by page type:

Next.js bulk static generation patterns

Pattern 1 - Database-driven generateStaticParams

The most common pattern. Query your database at build time to produce the params list.

// app/[service]/[state]/[city]/page.tsx
import { db } from '@/lib/db';
import { notFound } from 'next/navigation';

type Params = { service: string; state: string; city: string };

export async function generateStaticParams(): Promise<Params[]> {
  // Only generate pages that pass quality gate
  const pages = await db.locationPages.findMany({
    where: {
      qualityScore: { gte: 70 },
      isActive: true,
    },
    select: {
      serviceSlug: true,
      stateSlug: true,
      citySlug: true,
    },
  });

  return pages.map((p) => ({
    service: p.serviceSlug,
    state: p.stateSlug,
    city: p.citySlug,
  }));
}

export const dynamicParams = false; // 404 for any params not in generateStaticParams

Pattern 2 - CSV/JSON file-driven generation (no database)

Good for bootstrapping a pSEO project from a spreadsheet or data export.

// lib/pSEO-data.ts
import fs from 'fs';
import path from 'path';
import { parse } from 'csv-parse/sync';

export interface LocationRow {
  city: string;
  state: string;
  citySlug: string;
  stateSlug: string;
  providerCount: number;
  averagePrice: number;
  topProviders: string; // JSON stringified array in CSV
}

export function loadLocationData(): LocationRow[] {
  const csvPath = path.join(process.cwd(), 'data', 'locations.csv');
  const content = fs.readFileSync(csvPath, 'utf-8');
  return parse(content, { columns: true, cast: true });
}

// app/[city]/page.tsx
import { loadLocationData } from '@/lib/pSEO-data';

export async function generateStaticParams() {
  const rows = loadLocationData();
  return rows
    .filter((r) => r.providerCount >= 5) // quality gate
    .map((r) => ({ city: r.citySlug }));
}

Pattern 3 - Incremental Static Regeneration for live data

For pSEO pages where data changes regularly (prices, inventory, ratings).

// app/[city]/[service]/page.tsx
export const revalidate = 86400; // revalidate every 24 hours

// Or for on-demand revalidation from a webhook:
// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';

export async function POST(request: Request) {
  const { secret, citySlug, serviceSlug } = await request.json();
  if (secret !== process.env.REVALIDATION_SECRET) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
  revalidatePath(`/${citySlug}/${serviceSlug}`);
  return Response.json({ revalidated: true });
}

Astro bulk static generation patterns

Astro's content collections and dynamic routes work well for file-based pSEO.

// src/pages/[city]/[service].astro
---
import { getCollection } from 'astro:content';
import LocationTemplate from '@/components/LocationTemplate.astro';

export async function getStaticPaths() {
  const locations = await getCollection('locations', ({ data }) => {
    return data.providerCount >= 5; // quality gate
  });

  return locations.map((location) => ({
    params: {
      city: location.data.citySlug,
      service: location.data.serviceSlug,
    },
    props: { location },
  }));
}

const { location } = Astro.props;
---

<LocationTemplate data={location.data} />

For large datasets, Astro's build parallelism is faster than Next.js getStaticPaths when generating 10,000+ pages. Benchmark before committing to a framework at scale.

Quality scoring algorithm

Build a quality score before any page is published. The score gates what gets generated.

// lib/quality-score.ts

export interface PageQualityResult {
  score: number;       // 0-100
  grade: 'A' | 'B' | 'C' | 'F';
  passes: boolean;     // true if score >= threshold
  reasons: string[];   // why points were deducted
}

interface LocationPageData {
  providerCount: number;
  topProviders: unknown[];
  averagePrice: number;
  localStat: string;
  reviewCount: number;
  nearbyLocations: string[];
  uniqueBodyWords: number; // word count of unique (non-boilerplate) content
}

export function scoreLocationPage(
  data: LocationPageData,
  threshold = 65
): PageQualityResult {
  let score = 0;
  const reasons: string[] = [];

  // Provider data quality (30 points)
  if (data.providerCount >= 10) score += 30;
  else if (data.providerCount >= 5) score += 20;
  else { score += 0; reasons.push(`Low provider count: ${data.providerCount}`); }

  // Pricing data present (20 points)
  if (data.averagePrice > 0) score += 20;
  else reasons.push('No average price data');

  // Local stat present (15 points)
  if (data.localStat && data.localStat.length >= 30) score += 15;
  else reasons.push('Missing or thin local stat');

  // Review data (15 points)
  if (data.reviewCount >= 10) score += 15;
  else if (data.reviewCount >= 3) score += 8;
  else reasons.push(`Insufficient reviews: ${data.reviewCount}`);

  // Internal linking potential (10 points)
  if (data.nearbyLocations.length >= 4) score += 10;
  else reasons.push('Not enough nearby locations for internal links');

  // Unique content density (10 points)
  if (data.uniqueBodyWords >= 200) score += 10;
  else reasons.push(`Low unique word count: ${data.uniqueBodyWords}`);

  const passes = score >= threshold;
  const grade = score >= 85 ? 'A' : score >= 70 ? 'B' : score >= 55 ? 'C' : 'F';

  return { score, grade, passes, reasons };
}

Run this during generateStaticParams / getStaticPaths and log all failed pages to a file for review. Do not silently drop them - you want to know what data is missing.

// scripts/quality-audit.ts
import { loadAllLocationData } from '@/lib/data';
import { scoreLocationPage } from '@/lib/quality-score';
import fs from 'fs';

const all = await loadAllLocationData();
const failed = all
  .map((page) => ({ page, result: scoreLocationPage(page) }))
  .filter(({ result }) => !result.passes);

console.log(`Quality audit: ${failed.length}/${all.length} pages below threshold`);

fs.writeFileSync(
  'reports/quality-audit.json',
  JSON.stringify(failed, null, 2)
);

Batch publishing cadence

Publishing schedule to avoid triggering Google's quality review systems:

Publish via sitemap submission, not manual URL inspection. Submitting 10,000 URLs manually via Search Console wastes your inspection quota. Instead, submit the sitemap index and let Googlebot discover pages at its own crawl rate.

Avoid mass deletions. If a page gets deindexed, do not delete it - redirect it to the hub page. Mass 404s damage crawl budget trust. Only hard-delete pages that were never indexed.