Internal Linking - Fix Underlinked Pages
Your audit flagged dozens of underlinked pages. Now you're deciding whether to just run the fix or whether something could go wrong first.
The `audit` command reports underlinked pages when fewer than 3 other pages link to them. Orphan pages with 0 inbound links receive no internal PageRank, so Google can find them through the sitemap but has no signal about their importance. Pages with 1-2 links are weakly connected. The fix is `crosslink`, but before you run it, the situation on your site determines whether that's the right next step or whether something else needs to happen first.
The audit output splits into two sections: HEALTH, which gives you the count, and ACTION, which lists the worst offenders by name with their inbound link counts. Pages showing 0 inbound links are orphans. Pages showing 1-2 are weakly connected. Both groups appear in the same list, but they may not have the same fix. An orphan with zero traffic and keyword overlap with another page is a candidate for deletion, not crosslinking. Before you run `crosslink`, it's worth confirming these pages should exist at all.
`crosslink` costs $0.06 per page. For 47 pages that's $2.82. Wire reads each underlinked page, scans other pages in the same section for natural insertion points, generates contextual links using Claude, and validates every link against your site directory. It won't link to pages that don't exist. What it generates depends entirely on whether your existing pages contain text that naturally references the underlinked page's topic. If your content is thin, the links may be sparse or forced.
The `--dry-run` flag writes `.preview` files and shows a diff for each page without saving changes. You're looking for four things: links pointing to real pages, anchor text that describes the destination in 2-5 words, links placed inside body paragraphs rather than forced into unrelated sentences, and no duplicate links to the same destination on a single page. If a diff shows a link wedged into a paragraph that has nothing to do with the destination, that's a signal the source page doesn't have enough relevant content to support the link naturally.
A 23-million-link study found pages with exact-match anchor text receive 5x more organic traffic than pages without. But the risk runs both ways. Google's 2024 API leak confirmed an explicit demotion called `anchorMismatchDemotion` for pages where inbound anchor text doesn't match the page's topic. Wire varies anchor text across pages by design, so if every page linking to the same destination uses identical phrasing, something in the generation went wrong. The other failure mode is anchors over 5 words, which Google may ignore entirely.
Three situations make crosslink the wrong tool. First: a page with 0 inbound links, 0 impressions, and keyword overlap with a page you already have. The audit flags this as a dead page, not an underlinked page. Crosslinking it adds links to something that should be merged or deleted. Second: a page pending merge or differentiation. Wire skips these automatically, but if you've resolved the overlap outside Wire, the skip may still be active. Third: a page modified within the last 28 days, which Wire skips to avoid churn on content that's still changing.
After crosslink completes, run `audit` again on the same section. The HEALTH indicator for a resolved section flips from `-` to `+`, and the underlinked count disappears from the output. If some pages still show as underlinked after crosslink ran, either those pages were skipped (recently modified, pending merge, or flagged as dead) or the pages linking to them don't contain text that references their topic. Crosslink can only add links where the surrounding text supports them. A page that no other page ever mentions in its body text will stay underlinked.
CompareStack has 200 vendor profiles. The audit shows - 47 underlinked page(s) (<3 inbound links). That means 47 pages have fewer than 3 other pages linking to them. Google struggles to find and rank pages that the site itself barely references.
This guide shows how to find underlinked pages, fix them with the crosslink command, and verify the results.
Find Underlinked Pages
python -m wire.chief audit vendors
The HEALTH section shows the count:
The ACTION section lists the worst offenders:
Pages with 0 inbound links are orphans. Google can find them through the sitemap, but they receive no internal PageRank. Pages with 1-2 links exist in the link graph but are weakly connected.
Run Crosslink
python -m wire.chief crosslink vendors
Wire processes each underlinked page:
- Reads the page content and identifies its topic
- Scans all other pages in the topic for natural insertion points
- Generates contextual links using Claude, placed where they fit the surrounding text
- Validates every link against the site directory. No links to pages that don't exist.
Cost: $0.06 per page. For 47 pages: $2.82.
What the Links Look Like
Before crosslink, the betacorp vendor page mentions OCR processing but doesn't link to the acme-ocr page:
## Key Features
BetaCorp processes invoices, receipts, and purchase orders.
The OCR engine handles 47 languages with 96.2% accuracy
on the SROIE benchmark.
After crosslink:
## Key Features
BetaCorp processes invoices, receipts, and purchase orders.
The OCR engine handles 47 languages with 96.2% accuracy
on the SROIE benchmark, comparable to
[ACME OCR's multi-language pipeline](/vendors/acme-ocr/).
The link is contextual. It appears where the text naturally references something that another page covers in depth. It uses descriptive anchor text (not "click here" or "read more").
Anchor Text Rules
Wire follows strict anchor text rules from the styleguide. These rules exist because the evidence is strong:
Descriptive, 2-5 words. Zyppy's 23-million-link study found pages with exact-match anchor text receive 5x more organic traffic than pages without. The anchor tells Google what the destination page is about.
| Good | Bad | Why |
|---|---|---|
[ACME OCR's accuracy benchmarks](/vendors/acme-ocr/) |
[click here](/vendors/acme-ocr/) |
"click here" tells Google nothing about the destination |
[invoice processing comparison](/comparisons/acme-vs-betacorp/) |
[this page](/comparisons/acme-vs-betacorp/) |
"this page" wastes the anchor text signal |
[BetaCorp](/vendors/betacorp/) |
[BetaCorp's industry-leading enterprise document intelligence platform](/vendors/betacorp/) |
Too long. Google may ignore anchors over ~5 words. |
First mention only. Wire links the first mention of a topic, not every mention. Repeating the same link 5 times on a page adds noise, not signal.
Varied anchors across pages. seo.ai's study of 1,000+ sites found pages with high anchor text diversity ranked at position 1.3 on average versus 3.5 for low-diversity sites. If every page links to acme-ocr with the exact same anchor, vary it: "ACME's OCR engine", "ACME OCR benchmarks", "ACME's document processing".
What Google's API Leak Revealed
The 2024 API leak confirmed three internal linking signals:
anchorMismatchDemotion. An explicit ranking demotion for pages where inbound anchor text doesn't match the page's topic. Linking from a cooking page to a car insurance page with optimized anchor text can trigger this. Wire's crosslink only adds links between topically related pages within the same topic.
droppedLocalAnchorCount. Google counts how many internal link anchors it chose to ignore. Navigation links, footer links, and boilerplate links are dropped. Only contextual body links consistently count. Wire adds links inside article body text, not sidebars or footers.
homePageRank. The homepage has its own PageRank score. Fresh pages inherit it temporarily. Pages that never get internal links stay dependent on this inherited score. Crosslinking gives pages their own link equity.
Sources: iPullRank API leak analysis, Zyppy 23M links study.
Preview Before Applying
Use --dry-run to see what crosslink would add without saving:
python -m wire.chief crosslink vendors --dry-run
Wire writes .preview files and shows a diff for each page. Review the diffs to verify:
- Links point to real pages
- Anchor text is descriptive
- Links appear in natural positions (not forced into unrelated paragraphs)
- No duplicate links to the same destination
Verify Results
After crosslink completes, run the audit again:
python -m wire.chief audit vendors
Before:
After:
The 47 underlinked pages now have 3+ inbound links each. The HEALTH indicator flips from - to +.
AutoFix München Example
AutoFix has 45 service pages. The audit shows 6 underlinked pages:
After crosslink:
- The bremsen page now links to stossdaempfer ("Verschlissene Stoßdämpfer beeinträchtigen auch den Bremsweg.")
- The motor page now links to zuendkerzen and lichtmaschine in the diagnostic section
- The getriebe page now links to kupplung where it discusses manual transmission wear
Each link makes sense in context. A reader on the bremsen page who cares about stopping distance would naturally want to know about shock absorbers. The link serves the reader and the search engine.
Total cost: $0.36 (6 pages at $0.06 each).
When Not to Crosslink
Crosslink is not always the right fix:
Orphan pages with zero traffic. If a page has 0 inbound links AND 0 impressions AND other pages already cover its keywords, the audit flags it as a dead page, not an underlinked page. Dead pages should be merged or deleted, not crosslinked.
Pages blocked by overlap. If a page is pending merge or differentiation, crosslink skips it. Adding links to a page that's about to be merged wastes the API call. Fix overlaps first, then crosslink.
Pages touched within 28 days. Wire tracks when pages were last modified. Recently touched pages are skipped to avoid churn. If you need to force crosslink on a fresh page, remove the date: field from its frontmatter temporarily.