Internal linking guideline
A guideline summarizing the criteria for how to add internal links when writing a new article or updating an existing one. Use it as an operational rule for growing a site that boosts SEO crawlability while making it easy for readers to discover related topics.
Why — why internal links matter
Internal links (links from one article to another within the same site) are valuable from three perspectives.
1. Search engine crawlability
Google's crawler discovers your site by following internal links. When articles are not linked to each other and are connected only through the sidebar, the deeper an article sits in the hierarchy, the less often it tends to be crawled. Links in the body make it easier for an article to be recognized as "important — referenced by many others."
2. Diversifying anchor text
Docusaurus's standard "previous / next article" navigation (the paginator) uses mechanical anchor text like "Previous" and "Next." Links in the body let you diversify anchor text with natural context, as in "when you check the naming conventions." This serves as a quality signal for search engines.
3. Reader discoverability
Stating "people who read this article might also like this one" in the body increases time on site + page views per session. This is a plus for the "user satisfaction" signal that search engines look at, and for the reader's learning experience.
What — definitions of terms
| Term | Meaning | Example on this site |
|---|---|---|
| Hub article | The entry point for one theme; an index that branches out to multiple spoke articles | docs/intro, docs/clean-code |
| Spoke article | An individual topic derived from a hub; a deep-dive article | docs/clean-code/naming, docs/clean-code/functions |
| Cross-link | A bidirectional reference such as Blog ↔ Docs, complementing context | A hands-on Blog article ↔ a standards Docs article |
With the hub-and-spoke mental model, picture the whole site connected by "groups of spokes derived from hubs" + "Blog ↔ Docs cross-links."
How — three recommended patterns
Pattern 1: in-context body links (top priority)
Where you want the reader to reference a related topic in the flow of reading, turn natural language into anchor text and add a link.
Given TypeScript's [naming conventions](../clean-code/naming.md), this variable should be given a meaningful name like `userCount`.
This has the highest priority because it satisfies both anchor-text diversification and a natural reading path for the reader.
Pattern 2: a trailing "read next" section
Place an explicit guidance block at the end of a chapter. It is especially effective in hub articles and in the final installment of a series.
## Read next
- [Introduction](../intro.md) — back to the big picture of Introduction to Clean Code
- [Naming conventions](./naming.md) — the first chapter of an individual topic
This manual end-of-page guidance complements the related-posts plugin (an automatic calculation based on tag-match scores, showing up to four items at the end of an article). The difference is that you can explicitly state "I want you to read this."
Pattern 3: embedding links in a mermaid diagram
Adding external links to mermaid nodes with click turns the diagram itself into a visual table of contents.
Use it when you want to give an overview of an entire series.
Example — Bad vs. Good
Bad: a chapter with no internal links
---
title: Function design
---
Keep functions single-responsibility. Use early returns to keep nesting shallow.
(Zero links to other chapters in the body; the end is left to the paginator too.)
→ Readers have to navigate the sidebar themselves. From Google's view, too, the crawl path is thin.
Good: in-context body links + trailing guidance
---
title: Function design
---
Keep functions single-responsibility. Combined with [naming conventions](./naming.md), the intent becomes even clearer.
Use [early returns](./conditionals.md#use-early-returns) to keep nesting shallow.
## Read next
- [Loops](./loops.md) — how to write loops inside a function
- [TypeScript Tips](./typescript-tips.md) — type design for function signatures
→ Two in-context body links + two trailing guidance links, so the reader flows naturally to the articles they should read next.
Summary — a checklist for writing new articles
When writing a new article or updating an existing one, self-review with the following checklist.
- Does the body contain at least one internal link (Pattern 1)?
- When you add a new spoke to a hub article, did you also add a reverse link on the hub side?
- Have you missed any situation that calls for a Blog ↔ Docs cross-reference (citing a Docs standard in a Blog post, introducing a Blog example in the Docs)?
- Is the anchor text free of meaningless phrasing like "click here" or "details" (use natural language instead)?
- For articles that need a "read next" section (series / hub articles / finale), have you skipped it?
Finally, run VERIFY_LINKS=1 yarn build. If there is a broken link, the build fails with a non-zero exit (the normal build uses onBrokenLinks: 'warn', so warnings are easy to miss; use this throw-enabled command for verification). To verify everything at once, including textlint / typecheck, you can use yarn verify.
This site has a related-posts plugin (which automatically shows four related items at the end of an article); it is an automatic calculation based on tag-match scores. The internal links in this guideline are manual + natural-language anchors tailored to context, complementing the automatic calculation. The two are meant to be used together.