Internal Linking Strategy for Developer Docs and Blog Hubs

Architecture

Hub-and-spoke clusters for developer documentation sites

A hub-and-spoke model has one pillar page (the hub) that covers a broad topic comprehensively, and multiple supporting posts (spokes) that go deep on subtopics. The hub links to every spoke; every spoke links back to the hub and to 2-3 peer spokes.

For a site like fallback.pics, the hub might be 'Complete Guide to Image Placeholders in Web Development'. The spokes are posts on specific frameworks (Vue, Next.js, Shopify), use cases (avatars, heroes, OG images), and infrastructure (CDN caching, Docker, Cloudflare Workers).

Search engines use the link graph to understand content hierarchy. A spoke post about MUI avatar fallbacks that links back to the hub signals that the MUI post is part of the broader image placeholders topic — helping both pages rank for related queries.

Anchor text

Anchor text patterns that work for technical content

Technical anchor text should match the primary keyword of the target page where natural to do so, but should read like human prose, not keyword stuffing. 'See the MUI avatar fallback guide' is correct. 'Click here for more information' is wasted link equity.

Vary anchor text for pages that receive many inbound internal links. If twenty posts link to the hub page, use slightly different phrases: 'complete image placeholder guide', 'placeholder image overview', 'our full walkthrough'. This avoids over-optimization signals while still communicating topical relevance.

For documentation cross-links, prefer inline contextual links over footer 'related articles' lists. A link inside a relevant paragraph transfers more relevance signal than a link in a sidebar widget. Both help, but inline links have more weight.

Data-driven links

Surfacing related posts programmatically from blog data

Hardcoding internal links in every blog post body is unmaintainable at scale. Instead, define a `related` array in each post's data object and render a 'Related posts' section in the blog article layout. This makes internal links systematic and easy to audit.

For deeper automation, compute related posts from shared tags and category membership at build time. Posts sharing two or more tags are strong candidates for cross-linking. A build script can generate a `related` array for any post that does not have one defined manually.

// scripts/suggest-related.mjs
// Run at build time to suggest related posts for new content

import { blogPosts } from '../src/data/blogPosts.js';

function jaccard(a, b) {
  const setA = new Set(a);
  const intersection = b.filter(t => setA.has(t)).length;
  return intersection / (setA.size + b.length - intersection);
}

for (const post of blogPosts) {
  const candidates = blogPosts
    .filter(p => p.slug !== post.slug)
    .map(p => ({ slug: p.slug, score: jaccard(post.tags, p.tags) }))
    .sort((a, b) => b.score - a.score)
    .slice(0, 3)
    .map(p => p.slug);

  if (post.related.length === 0) {
    console.log(`${post.slug}:\n  suggested: ${candidates.join(', ')}`);
  }
}

Link placement

Where to place internal links in developer blog posts

Each post should have internal links in at least two places: inline within the first 300 words (establishes context early for crawlers) and in a dedicated 'Related' section at the end (serves readers who finished the post and want more). A third placement inside a code comment or example is natural for technical content.

The final section of a post — often a 'Resources' or 'Further reading' section — is a good place to consolidate links to both the documentation and to 2-3 related posts. Use the full URL so readers can see the destination without hovering.

# Final section template for developer blog posts

## Further reading

- [Complete Image Placeholder Guide](https://fallback.pics/blog/complete-guide-to-image-placeholders-in-web-development/) — the hub page for this topic cluster
- [Placeholder Image API Reference](https://fallback.pics/placeholder-image-api/) — URL syntax, parameters, and format options
- [React Image Fallback Patterns](https://fallback.pics/blog/react-image-fallback-patterns/) — onerror, custom hooks, and next/image
- [shadcn Avatar Fallback Src](https://fallback.pics/blog/shadcn-avatar-fallback-src/) — Radix Avatar with external fallback images

Audit

Auditing your existing internal link graph

Run Screaming Frog or a site:// crawl to export internal links. Look for posts with zero inbound internal links — these are 'orphan pages' that receive no equity from the rest of the site. Add at least one inbound link to every orphan from a topically relevant post or from the hub.

Look for pages with a high number of inbound links but very few outbound links to peer spokes. These are link equity sinks. Add 2-3 outbound links from the most-linked pages to distribute equity to spoke pages that are underperforming.

Check anchor text diversity on the most-linked pages. If 80% of internal links use identical anchor text, vary the phrasing in newer posts. Crawlers accept some repetition but flag extremely uniform anchor text as a signal of unnatural optimization.

Cluster map

Building a visual topic cluster map for content planning

A simple spreadsheet with columns for slug, hub, cluster (e.g. 'CMS Workflows', 'Performance', 'Mobile UX'), and inbound/outbound link counts is enough to identify gaps. Post this in your team's wiki and update it when new posts go live.

For the fallback.pics content hub, the current post set spans ten clusters. Each cluster should have at least one post that links back to the site's main documentation pages. If a cluster has five posts but none of them links to `/docs/` or `/placeholder-image-api/`, that cluster is not contributing to the product pages' authority.

https://fallback.pics/docs/
https://fallback.pics/placeholder-image-api/
https://fallback.pics/blog/complete-guide-to-image-placeholders-in-web-development/
https://fallback.pics/blog/broken-images-seo-fallback-fix/