Linking

Every link on your docs site serves one of three jobs: route the reader to a prerequisite, route them to a related-but-adjacent topic, or acknowledge an external source. Each job wants a different pattern. Sloppy linking — "click here", orphan pages, dead external refs — erodes both SEO and reader trust.

This guide covers the linking patterns that hold up.

The three link jobs

Descriptive anchor text

Screen reader users, SEO crawlers, and skimmers all pull anchor text to decide whether to follow a link. "Click here" gives them nothing.

❌ For custom domain setup, [click here](/deploy/custom-domain).
❌ Read more about [rate limits](/api/rate-limits).
❌ See [this page](/optimize/seo) for SEO info.

✅ See the [custom domain guide](/deploy/custom-domain) for DNS records.
✅ For rate-limit headers, see [API rate limits](/api/rate-limits).
✅ The [SEO optimise page](/optimize/seo) covers sitemap + robots config.

Rules:

• Anchor text describes the destination, not the action. "Custom domain setup" beats "click here".

• Anchor text reads naturally in prose. Avoid awkward wrapping like "[here](/…)".

• Avoid link text that duplicates with the surrounding sentence. If the prose says "see custom domain setup", don't link the whole phrase — link just the noun: "see custom domain setup".

Internal linking strategy

Topical clusters, not flat lists

Topical authority in SEO comes from cluster structure: one pillar page that broadly covers a topic, linked to + from N supporting pages that each cover a narrower sub-topic.

                    /deploy/custom-domain           (pillar)
                          │
      ┌──────────┬────────┼────────┬──────────┐
      ▼          ▼        ▼        ▼          ▼
 /deploy/      /deploy/  /deploy/ /deploy/   /deploy/
 cloudflare  vercel   route-53  monorepo   troubleshooting
 (support)   (support) (support) (support)  (support)

Patterns:

• Pillar links OUT to each supporting page. "For Cloudflare specifics, see Cloudflare custom domain."

• Supporting pages link BACK to the pillar. "For general custom-domain setup, see the custom domain overview."

• Supporting pages link SIDEWAYS to 2-3 sibling supporting pages. Not to all of them — cross-linking too densely dilutes signal.

Every page links to 3-5 other pages

Minimum viable cross-link density. Pages with zero internal links are orphans — they exist but nothing points to them. Google discovers them via the sitemap but ranks them poorly because no internal signal confirms they matter.

Quick audit:

# Rough count of internal links per page
for f in docs/**/*.mdx; do
  count=$(grep -oE '\]\(/[^)]+\)' "$f" | wc -l | tr -d ' ')
  if [ "$count" -lt 3 ]; then
    echo "$count  $f"
  fi
done

Fix pages with fewer than 3 internal links — add 2-3 related-page references in the prose or a "Related" section at the end.

"Related" section at the end

Every docs page should end with a ## Related section listing 4-8 cross-links grouped by relationship:

## Related

- [Prerequisites: custom domain setup](/deploy/custom-domain)
- [Next: configure SSL](/deploy/ssl-certificates)
- [Sibling: Cloudflare custom domain](/deploy/cloudflare-custom-domain)
- [Reference: schema for deploy settings](/configuration/schema-reference#deploy)
- [Guide: DNS concepts for writers](/guides/navigation)

Group by relationship, not alphabetically. Readers scan for the link that matches their next step.

External links

When to link out

Link externally when:

• The reader needs the authoritative external source — W3C specs, IETF RFCs, vendor API docs.

• You're acknowledging prior art — "The Diátaxis framework (Daniele Procida) …"

• The information is not yours to duplicate — legal text, vendor pricing tables, open-source changelogs.

Don't link externally:

• Just to cite a competitor's similar feature — invites readers to leave.

• To pad the "Related" section — internal links serve readers better.

• To your own blog posts as references in reference docs — blog posts go stale; prefer to move the canonical info into reference docs.

External link hygiene

[The WCAG 2.2 AA standard](https://www.w3.org/TR/WCAG22/)

• target="_blank" optional. Many users expect ctrl-click / cmd-click to decide themselves. Forcing new-tab is heavy-handed.

• rel="nofollow noreferrer" on user-generated content (comments, forum links — less relevant for curated docs).

• Check quarterly for link rot. Use a crawler like lychee:

lychee --exclude-all-private docs/**/*.mdx

Broken external links damage reader trust. Replace with updated URL or Internet Archive snapshot (web.archive.org/web/YYYYMMDD/...).

Open in same tab vs new tab

Docs convention: same tab. Users know how to ctrl-click if they want a new tab. Forcing new tab breaks the back button.

Exceptions where target="_blank" makes sense:

• External downloads — "Download the migration tool" (keeps doc open).

• Third-party integrations where you explicitly want the reader to compare tabs.

Anchor links (same-page)

Long pages benefit from a "jump to" pattern for the reader who already read the top and wants to get back to section X.

NookDocs auto-generates IDs from heading text:

## Rate limit headers

...later on the page...

For implementation details, see [rate limit headers](#rate-limit-headers).

ID generation rules:

• Lowercase

• Spaces → hyphens

• Punctuation stripped

• Duplicate headings on same page get numeric suffixes (#intro-2)

Explicit ID override:

## Custom heading text {#my-custom-id}

...

Link with [any text](#my-custom-id).

Useful for stable deep-linking when you might rename the heading later.

Cross-version linking

When your docs carry multiple versions (v1, v2), link hygiene matters more:

• Same-version links — relative [...](concept) stays within the current version.

• Cross-version links — explicit version prefix [v1 version of X](/v1/x) when you want to reference an older version's behaviour.

• Canonical version — the default: true version is the canonical URL. Non-default versions carry <link rel="canonical"> back to the default.

See versioning for the mechanics.

Link audit routine

Monthly, 30 minutes:

lychee --include-file-extensions=mdx docs/

# Any .mdx file never referenced by another
for page in $(find docs -name "*.mdx"); do
  slug=${page#docs/}
  slug=${slug%.mdx}
  refs=$(grep -rlE "]\(/$slug\)" docs/ | wc -l)
  [ "$refs" -eq 0 ] && echo "ORPHAN: $slug"
done

grep -oE '\(#[a-z0-9-]+\)' docs/**/*.mdx | sort -u

Link-dense vs link-sparse writing

Different docs areas want different density:

Linking too sparsely wastes internal SEO equity. Linking too densely fragments attention — the reader clicks away mid-read.

Common linking mistakes

Related

• SEO for docs — internal linking as ranking signal

• Content types — Diátaxis mode affects link density

• Style and tone — anchor-text writing as a voice decision

• Redirects — managing link equity through URL changes

• Navigation config — sidebar + tab structure