Safeguard
Developer Tools•

Internal links and anchor text for docs and blogs: what to do

Use real anchor elements, descriptive link text and at least one link to every page you care about. Google's crawlable links guidance applied to docs.

Safeguard Security Team
3 min read

Link every page you care about from at least one other page, use real anchor elements with an href, and write link text that describes the destination. Avoid "click here" and "read more". Google's guidance says to keep anchor text descriptive, concise and relevant.

Make links crawlable

Google can follow links that are a elements with an href pointing to a real URL. It cannot reliably follow span elements, onclick only handlers or javascript: URLs. Links inserted by JavaScript are fine if they use the same markup. See JavaScript docs site crawlability.

Write useful anchor text

From Google's guidance:

  • Put descriptive text inside the link. Empty links give little to work with.
  • For image links, the alt text acts as anchor text.
  • Avoid generic phrases and keyword stuffing.
  • Check whether the text makes sense on its own.
  • Avoid clusters of adjacent links. Space them out and use surrounding sentences for context.

Weak: "To rotate keys, click here." Better: "Follow the guide to rotate an API key."

Every page needs a path

Google says every page you care about should have a link from at least one other page on your site. Orphan pages, reachable only from a sitemap, are easy to miss. Run a crawl of your own site and list pages with zero internal links.

Build topic clusters by hand

For a docs site, link:

  • from reference pages to the how-to guides that use them,
  • from how-to guides to the explanation of the concept,
  • from explanation pages back to reference.

See docs structure by reader need. Link in context, in the sentence where a reader would want it, rather than in a block at the bottom.

How many links?

Google says there is no ideal number, but too many is a sign to trim. If every sentence has a link, none stands out.

External links

Linking out to sources can build trust. Google says to use nofollow for untrusted sources, and sponsored or ugc for paid or user generated links where appropriate.

URL hygiene that helps linking

Use readable URLs with descriptive words and hyphens rather than underscores, and standardize case because URLs are case sensitive. Link to the canonical form so signals are not split.

Quick check

Do buttons count as links?

Only if they render as an a element with an href. A button with a click handler is not reliably followed.

Should I add a related posts block to every page?

Related links help when they are chosen with care and described clearly. A random list adds noise.

Sources

Last reviewed: 19 October 2026.

Never miss an update

Weekly insights on software supply chain security, delivered to your inbox.

Self-healing security runs on Safeguard.

Your first fix PR is minutes away.

No sales call required, even your agent can complete the purchase over MCP.